Jump to Content

External Accounts

Webhook events for external account (bank account, payment method) verification status changes.

Events

Event Name	Status	Description
`external_account.approved`	APPROVED	External account verified and approved
`external_account.failed`	FAILED	External account verification failed

external_account.approved

Triggered when an external account (bank account or payment method) has been verified and approved for use.

Payload

{
  "event_name": "external_account.approved",
  "resource": {
    "type": "external_accounts",
    "id": "ea_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "idempotency_key": "678160c6-ca41-40ee-bfe7-35057ade157d"
  },
  "data": {
    "status": "APPROVED",
    "customer_id": "cus_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "account_id": "BZ-ABCD-1234",
    "external_account_id": "ea_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "created_at": "2024-01-22T12:00:00.000Z",
    "modified_at": "2024-01-22T12:30:00.000Z"
  }
}

Fields

Field	Type	Description
`status`	string	Always `APPROVED` for this event
`customer_id`	string	The customer ID who owns this external account
`account_id`	string	Account ID of the customer
`external_account_id`	string	Unique identifier for the external account
`created_at`	string	ISO 8601 timestamp when the account was created
`modified_at`	string	ISO 8601 timestamp when the account was last modified

external_account.failed

Triggered when an external account verification fails.

Payload

{
  "event_name": "external_account.failed",
  "resource": {
    "type": "external_accounts",
    "id": "ea_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "idempotency_key": "678160c6-ca41-40ee-bfe7-35057ade157d"
  },
  "data": {
    "status": "FAILED",
    "customer_id": "cus_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "account_id": "BZ-ABCD-1234",
    "external_account_id": "ea_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "created_at": "2024-01-22T12:00:00.000Z",
    "modified_at": "2024-01-22T12:30:00.000Z"
  }
}

Fields

Field	Type	Description
`status`	string	Always `FAILED` for this event
`customer_id`	string	The customer ID who owns this external account
`account_id`	string	Account ID of the customer
`external_account_id`	string	Unique identifier for the external account
`created_at`	string	ISO 8601 timestamp when the account was created
`modified_at`	string	ISO 8601 timestamp when the verification failed

Common Failure Reasons

External account verification may fail due to:

Invalid bank account details
Unsupported bank or routing number
Compliance restrictions
Unable to verify account ownership