Card account notification payloads

When you subscribe to a BILL event and the event triggers, BILL sends a notification to your provided notificationUrl. A card-account.created notification is sent when a card account is added to your BILL organization.

Sample `card-account.created` payload

In this sample unescaped JSON payload, the details of a card account are available. The notification includes a set of card-account fields.

Field	Description
`id`	BILL-generated ID of the card account. The value begins with `cat`.
`archived`	Set as `true` if the card account is archived
`createdTime`	Created date and time
`createdBy`	BILL-generated ID of the user that created the card account. This value begins with `006`.
`nameOnAccount`	Card account name
`brand`	Card brand. Brand names include Visa and Mastercard.
`type`	Card type (`CREDIT_CARD`, `DEBIT_CARD`, `PREPAID_CARD`, or `UNKNOWN`)
`status`	Card account status (`NOT_VERIFIED`, `VERIFIED`, `PENDING`, `BLOCKED`, `EXPIRED` or `INVALID`)
`last4`	Last four digits of the card
`expiration`	Card expiration month and year
`default`	Card payment defaults for BILL operations

{
  "metadata": {
    "eventId": "{event_id}",
    "subscriptionId": "{subscription_id}",
    "organizationId": "{organization_id}",
    "eventType": "card-account.created",
    "version": "1"
  },
  "card-account": {
    "id": "{cardaccount_id}",
    "archived": false,
    "createdTime": "2025-12-16T22:32:58.084+00:00",
    "createdBy": "{user_id}",
    "nameOnAccount": "Noodle Soupsmith",
    "brand": "Visa",
    "type": "DEBIT_CARD",
    "status": "VERIFIED",
    "last4": "1111",
    "expiration": {
      "year": "2028",
      "month": "12"
    },
    "default": {
      "payables": true,
      "receivables": true,
      "funding": false,
      "disbursement": true
    }
  }
}

Sample `card-account.updated` payload

In this sample unescaped JSON payload, the details of an updated card account are available. The notification includes the card account id for identifying the card account in your organization. In addition, updatedTime provides the updated date and time.

{
  "metadata": {
    "eventId": "{event_id}",
    "subscriptionId": "{subscription_id}",
    "organizationId": "{organization_id}",
    "eventType": "card-account.updated",
    "version": 1
  },
  "card-account": {
    "id": "{cardaccount_id}",
    "updatedTime": "2025-12-20T22:32:58.084+00:00",
    "expiration": {
      "year": "2029",
      "month": "12"
    }
  }
}

Fields that trigger `card-account.updated` notifications

When changes are made to a set of fields in a card account, the card-account.updated event notification is triggered.

Field	Description
`expiration.year`	Card expiration year
`expiration.month`	Card expiration month

Sample card-account.created payload

Sample card-account.updated payload

Fields that trigger card-account.updated notifications

Sample `card-account.created` payload

Sample `card-account.updated` payload

Fields that trigger `card-account.updated` notifications