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

In 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. 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 includes amount, currency, and arrivesByDate.
The disbursementAccount object includes type and accountNumber.

{
    "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"
    }
}

❗️IMPORTANT

Sample payment.updated payloads

Before money movement

When money movement begins

❗️
IMPORTANT

Sample `payment.updated` payloads