Guides
System Status
Start typing to search…

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

In 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 the status changes

When you create a payment, BILL sends you payment.updated notifications with the payment status 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 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"
    }
}

Sample payment.failed payload

When 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.

createdTime

Payment created date and time

updatedTime

Payment updated date and time

fundingAccount

Payment funding information

vendor

Vendor information. This includes vendor id and name.

errors

Payment failed reason.

  • code: Error code
  • message: Error message
  • timestamp: Error date and time
{
    "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 21 days ago