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. All the fields are included in each card-account.created payload.

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
`updatedTime`	Updated date and time
`createdBy`	BILL-generated ID of the user that created the card account. This value begins with `006`.
`nameOnAccount`	Full name on card account
`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",
    "updatedTime": "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.

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

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