# Bank Account Events

Bank accounts are foundational to ACH transactions within the GrailPay platform, serving as the endpoints for debits and credits between payors and payees. Whether added through direct input or our Bank Link SDK, these accounts must be tracked and maintained throughout their lifecycle. GrailPay provides webhook events that notify you when a bank account has been successfully linked, failed to link, or has been removed. These events allow your system to react to key account changes in real time, helping to keep records accurate and ensuring smooth payment processing.

By handling bank account webhooks, your integration gains full visibility into the account lifecycle. For example, a failed bank link may prompt you to notify a user, while a successful link may trigger onboarding flows or transaction enablement.

All payloads below are shown in full, including the [event envelope](/docs/technical/webhooks/events/#event-envelope).

***

## `bank_account.removed`

This webhook event is triggered whenever a bank account is deleted from the GrailPay system. It allows your integration to stay in sync with the current state of user-linked financial accounts, ensuring that your records remain accurate and up-to-date.

```json title="Event"
{
  "event": "bank_account.removed",
  "event_uuid": "019d072d-1203-7695-842b-a15567fbb0d8",
  "event_occurred_at": "2026-04-05 14:28:33",
  "event_version": 3,
  "vendor_uuid": "019e2711-5a92-735d-a7d5-669aec76b54f",
  "data": {
    "entity": {
      "type": "merchant",
      "uuid": "019e0383-8075-7704-bcb6-9d8c08137977",
      "person_uuid": "019e0385-2d7d-7d5f-acae-5c4276d86b61"
    },
    "bank_account": {
      "uuid": "9b97f121-a449-4b52-9f36-6c55f18394d6",
      "aggregator_type": "manual",
      "provider_type": "manual",
      "account_name": "Acme, Inc",
      "account_type": "checking",
      "account_number": "1111222233330000",
      "routing_number": "011401533",
      "institution_name": "Bank of America",
      "aggregator": "mx",
      "is_default": true,
      "client_reference_id": "client-1234",
      "status": "connected",
      "timestamps": {
        "created_at": "2024-06-25 13:57:03"
      }
    }
  }
}
```

## `bank_account.link_failed`

This webhook event is triggered whenever a bank account fails to link successfully using GrailPay's [Bank Link SDK](/docs/technical/bank-link-sdk/overview). This allows your application to track and respond to failed bank connection attempts, whether due to user cancellation, timeouts, or external provider errors.

```json title="Event"
{
  "event": "bank_account.link_failed",
  "event_uuid": "019d072d-1203-7695-842b-a15567fbb0d8",
  "event_occurred_at": "2026-04-05 14:28:33",
  "event_version": 3,
  "vendor_uuid": "019e2711-5a92-735d-a7d5-669aec76b54f",
  "data": {
    "entity": {
      "type": "merchant",
      "uuid": "019e0383-8075-7704-bcb6-9d8c08137977",
      "person_uuid": "019e0385-2d7d-7d5f-acae-5c4276d86b61"
    },
    "bank_account": {
      "uuid": "9b97f121-a449-4b52-9f36-6c55f18394d6",
      "aggregator_type": "manual",
      "provider_type": "manual",
      "account_name": "Acme, Inc",
      "account_type": "checking",
      "account_number": "1111222233330000",
      "routing_number": "011401533",
      "institution_name": "Bank of America",
      "aggregator": "mx",
      "is_default": true,
      "client_reference_id": "client-1234",
      "status": "connected",
      "timestamps": {
        "created_at": "2024-06-25 13:57:03"
      }
    },
    "failed_reason": "reason-bank-link-failed"
  }
}
```

## `bank_account.link_success`

This event is triggered when a bank account is successfully linked using GrailPay's [Bank Link SDK](/docs/technical/bank-link-sdk/overview). It confirms that the user has completed the linking process and the account is now available for transactions or balance checks. You can use this event to update your internal records, unlock funding workflows, or display confirmation messages to the user.

```json title="Event"
{
  "event": "bank_account.link_success",
  "event_uuid": "019d072d-1203-7695-842b-a15567fbb0d8",
  "event_occurred_at": "2026-04-05 14:28:33",
  "event_version": 3,
  "vendor_uuid": "019e2711-5a92-735d-a7d5-669aec76b54f",
  "data": {
    "entity": {
      "type": "merchant",
      "uuid": "019e0383-8075-7704-bcb6-9d8c08137977",
      "person_uuid": "019e0385-2d7d-7d5f-acae-5c4276d86b61"
    },
    "bank_account": {
      "uuid": "9b97f121-a449-4b52-9f36-6c55f18394d6",
      "aggregator_type": "manual",
      "provider_type": "manual",
      "account_name": "Acme, Inc",
      "account_type": "checking",
      "account_number": "1111222233330000",
      "routing_number": "011401533",
      "institution_name": "Bank of America",
      "aggregator": "mx",
      "is_default": true,
      "client_reference_id": "client-1234",
      "status": "connected",
      "timestamps": {
        "created_at": "2024-06-25 13:57:03"
      }
    }
  }
}
```