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.
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. - DISBURSEMENT_FAILED_ACTION_NEEDED : Disbursed payment is returned, but not voided as yet. Payer has the option to void & credit or void & reissue payment.- DISBURSEMENT_FAILED_VENDOR_BANK_REJECTED : Disbursed payment sent to the network vendor is returned, but not voided as yet. Payer must notify the network vendor to update their bank account in BILL.- FUNDING_FAILED_ACTION_NEEDED : BILL attempted to, but could not debit funds from the payer's funding account. However, BILL disbursed the payment, and the payer must wire funds to BILL.- FUNDS_ESCHEATED : Disbursed payment funds are not claimed by the vendor.- CANCELED : Payment is canceled.- FUNDING_FAILED_VOIDED : Payment is voided and is not eligible for a credit to the payer.- VOIDED : Payment is voided and is credited to the payer.- CLEARED : Disbursed payment is successfully settled by the vendor bank account. For example, a check is cashed, a virtual card payment is settled, or an ePayment is deposited to the vendor bank account.- DELIVERED : Payment is successfully sent, but the vendor is yet to take action to settle the payment. For example, an uncashed check or an unprocessed virtual card.- DISBURSEMENT_ON_HOLD : Disbursement is manually held for BILL to complete risk verification. BILL may reach out to the payer about the payment.- SENT : Disbursed payment is not delivered or settled as yet. The payment is issued or reissued, but not delivered (check or virtual card) or settled (ePayment).- PROCESSED : BILL has debited the payer's funding account (bank account, debit card, credit card, or BILL balance) to fund the payment.- FUNDING_STARTED : BILL has started to debit the payer's funding account (bank account, debit card, credit card, or BILL balance), but the process is not complete.- SCHEDULED : Payment is scheduled.- DISBURSEMENT_ON_HOLD_PAYER_IN_REVIEW : Disbursement is manually held for BILL to complete risk verification. BILL may reach out to the payer to complete verification.- FUNDING_ON_HOLD : BILL has not attempted to debit the payer account. The payer organization risk verification is incomplete.- VOID_PENDING : Payment is successfully sent and a void payment is requested.- WAITING_ON_APPROVAL : Payment is scheduled and is waiting on approval.- READY_TO_FUND : BILL is ready to start debiting the payer's funding account.- CANCELLATION_IN_PROGRESS : Payment cancellation is in progress.- PARTIALLY_CLAIMED : A virtual card payment has been claimed by the vendor for less than the full amount.- UNDEFINED : If none of the above conditions are met. |
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": "2024-12-16T23:56:52.127+00:00",
"updatedTime": "2024-12-17T23:56:52.127+00:00",
"processDate": "2024-12-17",
"funding": {
"amount": 228.99,
"currency": "USD",
"fundingAccount": {
"id": "bac01123ABC456DEF789",
"type": "BANK_ACCOUNT",
"name": "Noodle Soupsmith",
"accountNumber": "************1111"
}
},
"disbursement": {
"arrivesByDate": "2024-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": "2024-12-16T23:56:52.127+00:00",
"updatedTime": "2024-12-17T23:56:52.127+00:00",
"processDate": "2024-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": "2024-12-20",
"disbursementAccount": {
"type": "ACH",
"accountNumber": "******333"
}
},
"vendor": {
"id": "{vendor_id}",
"name": "Happy Music Supplies"
},
"billingType": "BILL_AUTOPAY"
}
}
Updated 3 days ago