Event structure

Bridge now supports webhook events for the following categories:

customer
kyc_link
liquidation_address.drain
static_memo.activity
transfer
virtual_account.activity
bridge_wallet.activity
card_account
card_transaction
posted_card_account_transaction
card_withdrawal
external_acccount
rfi (beta)

Additional event categories will be added soon.

💬 Feedback welcome — Let us know which event types you’d like to see prioritized next.

Supported Event Types

Category	Supported Event Types
`customer`	`created`, `updated`, `updated.status_transitioned`, `deleted`
`kyc_link`	`created`, `updated`, `updated.status_transitioned`
`liquidation_address.drain`	`created`, `updated`, `updated.status_transitioned`
`static_memo.activity`	`created`, `updated`
`transfer`	`created`, `updated`, `updated.status_transitioned`
`virtual_account.activity`	`created`, `updated`
`bridge_wallet.activity`	`created`, `updated`
`card_account`	`created`, `updated`, `updated.status_transitioned`
`card_transaction`	`created`, `updated`, `updated.status_transitioned`
`posted_card_account_transaction`	`created`
`external_acccount`	`created`, `updated`
`rfi`	`created`, `updated.status_transitioned`

Event Object Schema

Each webhook payload includes:

Field	Description
`api_version`	Current version of Bridge APIs (`v0`).
`event_id`	Globally unique event identifier. Useful as an idempotency key.
`event_category`	Category of the event (e.g., `virtual_account.activity`).
`event_type`	Formatted as `<event_category>.<mutation_type>`.
`event_object_id`	Same value as `event_object.id` (duplicated for easy access).
`event_object_status`	Optional. Populated when the object has a concept of status (e.g., `kyc_status`, `transfer_status`).
`event_object`	The full resource data, matching the structure in Bridge’s API reference.
`event_object_changes`	Diffs from the previous event (only present on updates).
`event_created_at`	Timestamp of the event in ISO 8601 format.

Event Object Schema Reference

The event_object field contains the full resource data, matching the structure returned by corresponding API endpoints. Webhooks and API responses use identical rendering logic, ensuring schema consistency.

Event Category	Schema Documentation
`transfer`	Transfer API Reference
`virtual_account.activity`	Virtual Account Activity
`customer`	Customer API Reference
`kyc_link`	KYC Link API Reference
`liquidation_address.drain`	Liquidation Address
`static_memo.activity`	Static Memo Activity
`bridge_wallet.activity`	Bridge Wallet transaction history API
`external_acccount`	External Account API Reference
`rfi`	Requests for Information (RFIs)

Supported Mutation Types

Each event can have the following mutation types:

created
updated
updated.status_transitioned (for state transitions like KYC or Transfer status)
deleted (if applicable)

Examples

Transfers

First event for a transfer: created, waiting on the customer’s deposit.

{
  "api_version": "v0",
  "event_id": "wh_123abc456def",
  "event_sequence": 1,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "transfer",
  "event_type": "transfer.created",
  "event_object_id": "tr_8e9a1f2c3d4b5a69",
  "event_object_status": "awaiting_funds",
  "event_object": {
    "id": "tr_8e9a1f2c3d4b5a69",
    "state": "awaiting_funds",
    "amount": "1500.00",
    "currency": "usd",
    "developer_fee": "0.0",
    "client_reference_id": null,
    "on_behalf_of": "cust_alice",
    "source": {
      "currency": "usdc",
      "from_address": "0x1111111111111111111111111111111111111111",
      "payment_rail": "polygon"
    },
    "destination": {
      "currency": "usd",
      "payment_rail": "ach",
      "external_account_id": "external-account-123"
    },
    "source_deposit_instructions": {
      "payment_rail": "polygon",
      "amount": "1500.00",
      "currency": "usdc",
      "to_address": "0x2222222222222222222222222222222222222222"
    },
    "created_at": "2025-07-22T11:26:55.000Z",
    "updated_at": "2025-07-22T11:26:55.000Z"
  },
  "event_object_changes": {},
  "event_created_at": "2025-07-22T11:26:55.000Z"
}

The customer’s deposit arrived and matched the expected amount.

{
  "api_version": "v0",
  "event_id": "wh_234bcd567efg",
  "event_sequence": 2,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "transfer",
  "event_type": "transfer.updated.status_transitioned",
  "event_object_id": "tr_8e9a1f2c3d4b5a69",
  "event_object_status": "funds_received",
  "event_object": {
    "id": "tr_8e9a1f2c3d4b5a69",
    "state": "funds_received",
    "amount": "1500.00",
    "currency": "usd",
    "developer_fee": "0.0",
    "client_reference_id": null,
    "on_behalf_of": "cust_alice",
    "source": {
      "currency": "usdc",
      "from_address": "0x1111111111111111111111111111111111111111",
      "payment_rail": "polygon"
    },
    "destination": {
      "currency": "usd",
      "payment_rail": "ach",
      "external_account_id": "external-account-123"
    },
    "created_at": "2025-07-22T11:26:55.000Z",
    "updated_at": "2025-07-22T11:28:10.000Z"
  },
  "event_object_changes": {
    "state": ["awaiting_funds", "funds_received"]
  },
  "event_created_at": "2025-07-22T11:28:10.000Z"
}

Flagged for manual compliance review after funds were received.

{
  "api_version": "v0",
  "event_id": "wh_345cde678fgh",
  "event_sequence": 3,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "transfer",
  "event_type": "transfer.updated.status_transitioned",
  "event_object_id": "tr_8e9a1f2c3d4b5a69",
  "event_object_status": "in_review",
  "event_object": {
    "id": "tr_8e9a1f2c3d4b5a69",
    "state": "in_review",
    "amount": "1500.00",
    "currency": "usd",
    "developer_fee": "0.0",
    "client_reference_id": null,
    "on_behalf_of": "cust_alice",
    "source": {
      "currency": "usdc",
      "from_address": "0x1111111111111111111111111111111111111111",
      "payment_rail": "polygon"
    },
    "destination": {
      "currency": "usd",
      "payment_rail": "ach",
      "external_account_id": "external-account-123"
    },
    "created_at": "2025-07-22T11:26:55.000Z",
    "updated_at": "2025-07-22T11:30:00.000Z"
  },
  "event_object_changes": {
    "state": ["funds_received", "in_review"]
  },
  "event_created_at": "2025-07-22T11:30:00.000Z"
}

Review cleared; the outbound ACH payment has been submitted.

{
  "api_version": "v0",
  "event_id": "wh_456def789ghi",
  "event_sequence": 4,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "transfer",
  "event_type": "transfer.updated.status_transitioned",
  "event_object_id": "tr_8e9a1f2c3d4b5a69",
  "event_object_status": "payment_submitted",
  "event_object": {
    "id": "tr_8e9a1f2c3d4b5a69",
    "state": "payment_submitted",
    "amount": "1500.00",
    "currency": "usd",
    "developer_fee": "0.0",
    "client_reference_id": null,
    "on_behalf_of": "cust_alice",
    "source": {
      "currency": "usdc",
      "from_address": "0x1111111111111111111111111111111111111111",
      "payment_rail": "polygon"
    },
    "destination": {
      "currency": "usd",
      "payment_rail": "ach",
      "external_account_id": "external-account-123",
      "trace_number": "091000019012345"
    },
    "created_at": "2025-07-22T11:26:55.000Z",
    "updated_at": "2025-07-22T12:15:00.000Z"
  },
  "event_object_changes": {
    "state": ["in_review", "payment_submitted"]
  },
  "event_created_at": "2025-07-22T12:15:00.000Z"
}

The transfer has passed validation and is queued to be submitted.

{
  "api_version": "v0",
  "event_id": "wh_567efg890hij",
  "event_sequence": 5,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "transfer",
  "event_type": "transfer.updated.status_transitioned",
  "event_object_id": "tr_8e9a1f2c3d4b5a69",
  "event_object_status": "payment_validated",
  "event_object": {
    "id": "tr_8e9a1f2c3d4b5a69",
    "state": "payment_validated",
    "amount": "1500.00",
    "currency": "usd",
    "developer_fee": "0.0",
    "client_reference_id": null,
    "on_behalf_of": "cust_alice",
    "source": {
      "currency": "usdc",
      "from_address": "0x1111111111111111111111111111111111111111",
      "payment_rail": "polygon"
    },
    "destination": {
      "currency": "usd",
      "payment_rail": "ach",
      "external_account_id": "external-account-123",
      "trace_number": "091000019012345"
    },
    "created_at": "2025-07-22T11:26:55.000Z",
    "updated_at": "2025-07-23T09:00:00.000Z"
  },
  "event_object_changes": {
    "state": ["payment_submitted", "payment_validated"]
  },
  "event_created_at": "2025-07-23T09:00:00.000Z"
}

Terminal success. Funds have settled with the recipient.

{
  "api_version": "v0",
  "event_id": "wh_678fgh901ijk",
  "event_sequence": 6,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "transfer",
  "event_type": "transfer.updated.status_transitioned",
  "event_object_id": "tr_8e9a1f2c3d4b5a69",
  "event_object_status": "payment_processed",
  "event_object": {
    "id": "tr_8e9a1f2c3d4b5a69",
    "state": "payment_processed",
    "amount": "1500.00",
    "currency": "usd",
    "developer_fee": "0.0",
    "client_reference_id": null,
    "on_behalf_of": "cust_alice",
    "source": {
      "currency": "usdc",
      "from_address": "0x1111111111111111111111111111111111111111",
      "payment_rail": "polygon"
    },
    "destination": {
      "currency": "usd",
      "payment_rail": "ach",
      "external_account_id": "external-account-123",
      "trace_number": "091000019012345"
    },
    "receipt": {
      "url": "https://dashboard.bridge.xyz/transaction/tr_8e9a1f2c3d4b5a69/receipt/receipt_xyz456",
      "exchange_fee": "0.0",
      "developer_fee": "0.0",
      "initial_amount": "1500.00",
      "subtotal_amount": "1500.00",
      "final_amount": "1500.00"
    },
    "created_at": "2025-07-22T11:26:55.000Z",
    "updated_at": "2025-07-24T08:05:00.000Z"
  },
  "event_object_changes": {
    "state": ["payment_validated", "payment_processed"]
  },
  "event_created_at": "2025-07-24T08:05:00.000Z"
}

Blocked: the on-behalf-of customer needs additional KYC before the transfer can proceed.

{
  "api_version": "v0",
  "event_id": "wh_789ghi012jkl",
  "event_sequence": 2,
  "event_developer_id": "dev_222bbb333ccc444ddd",
  "event_category": "transfer",
  "event_type": "transfer.updated.status_transitioned",
  "event_object_id": "tr_9f0b2a3d4e5c6b7a",
  "event_object_status": "kyc_required",
  "event_object": {
    "id": "tr_9f0b2a3d4e5c6b7a",
    "state": "kyc_required",
    "amount": "2500.00",
    "currency": "usd",
    "developer_fee": "0.0",
    "client_reference_id": null,
    "on_behalf_of": "cust_carol",
    "source": {
      "currency": "usdc",
      "from_address": "0x3333333333333333333333333333333333333333",
      "payment_rail": "ethereum"
    },
    "destination": {
      "currency": "usd",
      "payment_rail": "wire",
      "external_account_id": "external-account-456"
    },
    "created_at": "2025-07-20T09:00:00.000Z",
    "updated_at": "2025-07-20T09:05:00.000Z"
  },
  "event_object_changes": {
    "state": ["funds_received", "kyc_required"]
  },
  "event_created_at": "2025-07-20T09:05:00.000Z"
}

The customer submitted the requested KYC information; it’s under review.

{
  "api_version": "v0",
  "event_id": "wh_890hij123klm",
  "event_sequence": 3,
  "event_developer_id": "dev_222bbb333ccc444ddd",
  "event_category": "transfer",
  "event_type": "transfer.updated.status_transitioned",
  "event_object_id": "tr_9f0b2a3d4e5c6b7a",
  "event_object_status": "kyc_in_review",
  "event_object": {
    "id": "tr_9f0b2a3d4e5c6b7a",
    "state": "kyc_in_review",
    "amount": "2500.00",
    "currency": "usd",
    "developer_fee": "0.0",
    "client_reference_id": null,
    "on_behalf_of": "cust_carol",
    "source": {
      "currency": "usdc",
      "from_address": "0x3333333333333333333333333333333333333333",
      "payment_rail": "ethereum"
    },
    "destination": {
      "currency": "usd",
      "payment_rail": "wire",
      "external_account_id": "external-account-456"
    },
    "created_at": "2025-07-20T09:00:00.000Z",
    "updated_at": "2025-07-20T15:30:00.000Z"
  },
  "event_object_changes": {
    "state": ["kyc_required", "kyc_in_review"]
  },
  "event_created_at": "2025-07-20T15:30:00.000Z"
}

Blocked: the developer’s own business (KYB) verification must be completed before the transfer can proceed.

{
  "api_version": "v0",
  "event_id": "wh_901ijk234lmn",
  "event_sequence": 2,
  "event_developer_id": "dev_333ccc444ddd555eee",
  "event_category": "transfer",
  "event_type": "transfer.updated.status_transitioned",
  "event_object_id": "tr_0a1c3b4e5f6d7c8b",
  "event_object_status": "developer_kyb_required",
  "event_object": {
    "id": "tr_0a1c3b4e5f6d7c8b",
    "state": "developer_kyb_required",
    "amount": "5000.00",
    "currency": "usd",
    "developer_fee": "0.0",
    "client_reference_id": null,
    "on_behalf_of": "cust_dave",
    "source": {
      "currency": "usdc",
      "payment_rail": "bridge_wallet",
      "bridge_wallet_id": "wallet_dave_usdc"
    },
    "destination": {
      "currency": "usd",
      "payment_rail": "wire",
      "external_account_id": "external-account-789"
    },
    "created_at": "2025-07-19T10:00:00.000Z",
    "updated_at": "2025-07-19T10:01:00.000Z"
  },
  "event_object_changes": {
    "state": ["funds_received", "developer_kyb_required"]
  },
  "event_created_at": "2025-07-19T10:01:00.000Z"
}

The deposit received was less than the amount expected for the transfer.

{
  "api_version": "v0",
  "event_id": "wh_012jkl345mno",
  "event_sequence": 2,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "transfer",
  "event_type": "transfer.updated.status_transitioned",
  "event_object_id": "tr_1b2d4c5f6a7e8d9c",
  "event_object_status": "underfunded",
  "event_object": {
    "id": "tr_1b2d4c5f6a7e8d9c",
    "state": "underfunded",
    "amount": "1000.00",
    "currency": "usd",
    "developer_fee": "0.0",
    "client_reference_id": null,
    "on_behalf_of": "cust_erin",
    "source": {
      "currency": "usdc",
      "from_address": "0x4444444444444444444444444444444444444444",
      "payment_rail": "base"
    },
    "destination": {
      "currency": "usd",
      "payment_rail": "ach",
      "external_account_id": "external-account-321"
    },
    "created_at": "2025-07-18T14:00:00.000Z",
    "updated_at": "2025-07-18T14:20:00.000Z"
  },
  "event_object_changes": {
    "state": ["awaiting_funds", "underfunded"]
  },
  "event_created_at": "2025-07-18T14:20:00.000Z"
}

Blocked: a return_instructions.address is required before Bridge can proceed (or safely return funds) and none was provided.

{
  "api_version": "v0",
  "event_id": "wh_123klm456nop",
  "event_sequence": 2,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "transfer",
  "event_type": "transfer.updated.status_transitioned",
  "event_object_id": "tr_2c3e5d6a7b8f9e0d",
  "event_object_status": "missing_return_policy",
  "event_object": {
    "id": "tr_2c3e5d6a7b8f9e0d",
    "state": "missing_return_policy",
    "amount": "750.00",
    "currency": "usd",
    "developer_fee": "0.0",
    "client_reference_id": null,
    "on_behalf_of": "cust_frank",
    "source": {
      "currency": "usdc",
      "from_address": "0x5555555555555555555555555555555555555555",
      "payment_rail": "solana"
    },
    "destination": {
      "currency": "usd",
      "payment_rail": "ach",
      "external_account_id": "external-account-654"
    },
    "created_at": "2025-07-17T08:00:00.000Z",
    "updated_at": "2025-07-17T08:10:00.000Z"
  },
  "event_object_changes": {
    "state": ["funds_received", "missing_return_policy"]
  },
  "event_created_at": "2025-07-17T08:10:00.000Z"
}

The outbound payment could not be delivered to the destination (e.g. a closed bank account).

{
  "api_version": "v0",
  "event_id": "wh_234lmn567opq",
  "event_sequence": 5,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "transfer",
  "event_type": "transfer.updated.status_transitioned",
  "event_object_id": "tr_3d4f6e7b8c9a0f1e",
  "event_object_status": "undeliverable",
  "event_object": {
    "id": "tr_3d4f6e7b8c9a0f1e",
    "state": "undeliverable",
    "amount": "1200.00",
    "currency": "usd",
    "developer_fee": "0.0",
    "client_reference_id": null,
    "on_behalf_of": "cust_grace",
    "source": {
      "currency": "usdc",
      "from_address": "0x6666666666666666666666666666666666666666",
      "payment_rail": "ethereum"
    },
    "destination": {
      "currency": "usd",
      "payment_rail": "ach",
      "external_account_id": "external-account-987"
    },
    "created_at": "2025-07-16T10:00:00.000Z",
    "updated_at": "2025-07-16T12:00:00.000Z"
  },
  "event_object_changes": {
    "state": ["payment_submitted", "undeliverable"]
  },
  "event_created_at": "2025-07-16T12:00:00.000Z"
}

An unexpected processing error occurred. Bridge is investigating; the transfer is not yet in a terminal state.

{
  "api_version": "v0",
  "event_id": "wh_345mno678pqr",
  "event_sequence": 4,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "transfer",
  "event_type": "transfer.updated.status_transitioned",
  "event_object_id": "tr_4e5a7f8c9d0b1a2f",
  "event_object_status": "error",
  "event_object": {
    "id": "tr_4e5a7f8c9d0b1a2f",
    "state": "error",
    "amount": "900.00",
    "currency": "usd",
    "developer_fee": "0.0",
    "client_reference_id": null,
    "on_behalf_of": "cust_henry",
    "source": {
      "currency": "usdc",
      "from_address": "0x7777777777777777777777777777777777777777",
      "payment_rail": "polygon"
    },
    "destination": {
      "currency": "usd",
      "payment_rail": "wire",
      "external_account_id": "external-account-852"
    },
    "created_at": "2025-07-15T09:00:00.000Z",
    "updated_at": "2025-07-15T09:45:00.000Z"
  },
  "event_object_changes": {
    "state": ["payment_submitted", "error"]
  },
  "event_created_at": "2025-07-15T09:45:00.000Z"
}

The transfer was canceled before completion.

{
  "api_version": "v0",
  "event_id": "wh_456nop789qrs",
  "event_sequence": 2,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "transfer",
  "event_type": "transfer.updated.status_transitioned",
  "event_object_id": "tr_5f6b8a9d0e1c2b3a",
  "event_object_status": "canceled",
  "event_object": {
    "id": "tr_5f6b8a9d0e1c2b3a",
    "state": "canceled",
    "amount": "300.00",
    "currency": "usd",
    "developer_fee": "0.0",
    "client_reference_id": null,
    "on_behalf_of": "cust_iris",
    "source": {
      "currency": "usdc",
      "from_address": "0x8888888888888888888888888888888888888888",
      "payment_rail": "base"
    },
    "destination": {
      "currency": "usd",
      "payment_rail": "ach",
      "external_account_id": "external-account-741"
    },
    "created_at": "2025-07-14T13:00:00.000Z",
    "updated_at": "2025-07-14T13:05:00.000Z"
  },
  "event_object_changes": {
    "state": ["awaiting_funds", "canceled"]
  },
  "event_created_at": "2025-07-14T13:05:00.000Z"
}

The transfer (typically a static-template instance) was deactivated and will no longer accept funds.

{
  "api_version": "v0",
  "event_id": "wh_567opq890rst",
  "event_sequence": 2,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "transfer",
  "event_type": "transfer.updated.status_transitioned",
  "event_object_id": "tr_6a7c9b0e1f2d3c4b",
  "event_object_status": "deactivated",
  "event_object": {
    "id": "tr_6a7c9b0e1f2d3c4b",
    "state": "deactivated",
    "amount": "1500.00",
    "currency": "usd",
    "developer_fee": "0.0",
    "client_reference_id": null,
    "on_behalf_of": "cust_jack",
    "source": {
      "currency": "usdc",
      "from_address": "0x9999999999999999999999999999999999999999",
      "payment_rail": "ethereum"
    },
    "destination": {
      "currency": "usd",
      "payment_rail": "ach",
      "external_account_id": "external-account-963"
    },
    "template_id": "tmpl_abc123",
    "created_at": "2025-07-13T11:00:00.000Z",
    "updated_at": "2025-07-13T11:30:00.000Z"
  },
  "event_object_changes": {
    "state": ["awaiting_funds", "deactivated"]
  },
  "event_created_at": "2025-07-13T11:30:00.000Z"
}

Funds were returned to the source instead of reaching the destination.

{
  "api_version": "v0",
  "event_id": "wh_678pqr901stu",
  "event_sequence": 5,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "transfer",
  "event_type": "transfer.updated.status_transitioned",
  "event_object_id": "tr_3d4f6e7b8c9a0f1e",
  "event_object_status": "returned",
  "event_object": {
    "id": "tr_3d4f6e7b8c9a0f1e",
    "state": "returned",
    "amount": "1200.00",
    "currency": "usd",
    "developer_fee": "0.0",
    "client_reference_id": null,
    "on_behalf_of": "cust_grace",
    "source": {
      "currency": "usdc",
      "from_address": "0x6666666666666666666666666666666666666666",
      "payment_rail": "ethereum"
    },
    "destination": {
      "currency": "usd",
      "payment_rail": "ach",
      "external_account_id": "external-account-987"
    },
    "return_details": {
      "reason": "undeliverable_destination",
      "amount": "1200.00"
    },
    "created_at": "2025-07-16T10:00:00.000Z",
    "updated_at": "2025-07-16T18:00:00.000Z"
  },
  "event_object_changes": {
    "state": ["undeliverable", "returned"]
  },
  "event_created_at": "2025-07-16T18:00:00.000Z"
}

A refund of the original deposit has been initiated.

{
  "api_version": "v0",
  "event_id": "wh_789qrs012tuv",
  "event_sequence": 6,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "transfer",
  "event_type": "transfer.updated.status_transitioned",
  "event_object_id": "tr_3d4f6e7b8c9a0f1e",
  "event_object_status": "refund_in_flight",
  "event_object": {
    "id": "tr_3d4f6e7b8c9a0f1e",
    "state": "refund_in_flight",
    "amount": "1200.00",
    "currency": "usd",
    "developer_fee": "0.0",
    "client_reference_id": null,
    "on_behalf_of": "cust_grace",
    "source": {
      "currency": "usdc",
      "from_address": "0x6666666666666666666666666666666666666666",
      "payment_rail": "ethereum"
    },
    "destination": {
      "currency": "usd",
      "payment_rail": "ach",
      "external_account_id": "external-account-987"
    },
    "return_details": {
      "reason": "undeliverable_destination",
      "amount": "1200.00"
    },
    "created_at": "2025-07-16T10:00:00.000Z",
    "updated_at": "2025-07-17T09:00:00.000Z"
  },
  "event_object_changes": {
    "state": ["returned", "refund_in_flight"]
  },
  "event_created_at": "2025-07-17T09:00:00.000Z"
}

Terminal: the refund completed successfully and funds are back with the original sender.

{
  "api_version": "v0",
  "event_id": "wh_890rst123uvw",
  "event_sequence": 7,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "transfer",
  "event_type": "transfer.updated.status_transitioned",
  "event_object_id": "tr_3d4f6e7b8c9a0f1e",
  "event_object_status": "refunded",
  "event_object": {
    "id": "tr_3d4f6e7b8c9a0f1e",
    "state": "refunded",
    "amount": "1200.00",
    "currency": "usd",
    "developer_fee": "0.0",
    "client_reference_id": null,
    "on_behalf_of": "cust_grace",
    "source": {
      "currency": "usdc",
      "from_address": "0x6666666666666666666666666666666666666666",
      "payment_rail": "ethereum"
    },
    "destination": {
      "currency": "usd",
      "payment_rail": "ach",
      "external_account_id": "external-account-987"
    },
    "return_details": {
      "reason": "undeliverable_destination",
      "amount": "1200.00"
    },
    "receipt": {
      "destination_tx_hash": "5gJH6oXpZUNgC1QLh8mXNPF92LtLKzHZj5eHuQrdQAgC"
    },
    "created_at": "2025-07-16T10:00:00.000Z",
    "updated_at": "2025-07-17T15:00:00.000Z"
  },
  "event_object_changes": {
    "state": ["refund_in_flight", "refunded"]
  },
  "event_created_at": "2025-07-17T15:00:00.000Z"
}

Terminal: the attempted refund did not succeed. Contact Bridge support to resolve.

{
  "api_version": "v0",
  "event_id": "wh_901stu234vwx",
  "event_sequence": 7,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "transfer",
  "event_type": "transfer.updated.status_transitioned",
  "event_object_id": "tr_7b8d0c1f2a3e4d5c",
  "event_object_status": "refund_failed",
  "event_object": {
    "id": "tr_7b8d0c1f2a3e4d5c",
    "state": "refund_failed",
    "amount": "600.00",
    "currency": "usd",
    "developer_fee": "0.0",
    "client_reference_id": null,
    "on_behalf_of": "cust_kate",
    "source": {
      "currency": "usdc",
      "from_address": "0x1010101010101010101010101010101010101010",
      "payment_rail": "solana"
    },
    "destination": {
      "currency": "usd",
      "payment_rail": "ach",
      "external_account_id": "external-account-159"
    },
    "return_details": {
      "reason": "undeliverable_destination",
      "amount": "600.00"
    },
    "created_at": "2025-07-12T10:00:00.000Z",
    "updated_at": "2025-07-13T10:00:00.000Z"
  },
  "event_object_changes": {
    "state": ["refund_in_flight", "refund_failed"]
  },
  "event_created_at": "2025-07-13T10:00:00.000Z"
}

Liquidation Address Drains

A liquidation address drain moves funds out of a liquidation address and follows the same lifecycle as a transfer, from initial receipt through to final settlement or return.

A deposit was detected at the liquidation address and a drain record was created.

{
  "api_version": "v0",
  "event_id": "wh_d01awaiting",
  "event_sequence": 1,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "liquidation_address.drain",
  "event_type": "liquidation_address.drain.created",
  "event_object_id": "drn_6b2c3d4e5f6a7b8c",
  "event_object_status": "awaiting_funds",
  "event_object": {
    "id": "drn_6b2c3d4e5f6a7b8c",
    "customer_id": "cust_alice",
    "liquidation_address_id": "la_abc123def456",
    "amount": "250.00",
    "currency": "usdc",
    "state": "awaiting_funds",
    "deposit_tx_hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab",
    "deposit_tx_timestamp": "2025-07-22T11:25:00.000Z",
    "from_address": "0x1111111111111111111111111111111111111111",
    "destination": {
      "payment_rail": "ach",
      "currency": "usd",
      "external_account_id": "external-account-123"
    },
    "created_at": "2025-07-22T11:26:00.000Z",
    "updated_at": "2025-07-22T11:26:00.000Z"
  },
  "event_object_changes": {},
  "event_created_at": "2025-07-22T11:26:00.000Z"
}

The on-chain deposit has confirmed and matched the expected amount.

{
  "api_version": "v0",
  "event_id": "wh_d02funds",
  "event_sequence": 2,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "liquidation_address.drain",
  "event_type": "liquidation_address.drain.updated.status_transitioned",
  "event_object_id": "drn_6b2c3d4e5f6a7b8c",
  "event_object_status": "funds_received",
  "event_object": {
    "id": "drn_6b2c3d4e5f6a7b8c",
    "customer_id": "cust_alice",
    "liquidation_address_id": "la_abc123def456",
    "amount": "250.00",
    "currency": "usdc",
    "state": "funds_received",
    "deposit_tx_hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab",
    "deposit_tx_timestamp": "2025-07-22T11:25:00.000Z",
    "from_address": "0x1111111111111111111111111111111111111111",
    "destination": {
      "payment_rail": "ach",
      "currency": "usd",
      "external_account_id": "external-account-123"
    },
    "created_at": "2025-07-22T11:26:00.000Z",
    "updated_at": "2025-07-22T11:27:30.000Z"
  },
  "event_object_changes": {
    "state": ["awaiting_funds", "funds_received"]
  },
  "event_created_at": "2025-07-22T11:27:30.000Z"
}

Flagged for manual compliance review.

{
  "api_version": "v0",
  "event_id": "wh_d03review",
  "event_sequence": 3,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "liquidation_address.drain",
  "event_type": "liquidation_address.drain.updated.status_transitioned",
  "event_object_id": "drn_6b2c3d4e5f6a7b8c",
  "event_object_status": "in_review",
  "event_object": {
    "id": "drn_6b2c3d4e5f6a7b8c",
    "customer_id": "cust_alice",
    "liquidation_address_id": "la_abc123def456",
    "amount": "250.00",
    "currency": "usdc",
    "state": "in_review",
    "deposit_tx_hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab",
    "deposit_tx_timestamp": "2025-07-22T11:25:00.000Z",
    "from_address": "0x1111111111111111111111111111111111111111",
    "destination": {
      "payment_rail": "ach",
      "currency": "usd",
      "external_account_id": "external-account-123"
    },
    "created_at": "2025-07-22T11:26:00.000Z",
    "updated_at": "2025-07-22T11:35:00.000Z"
  },
  "event_object_changes": {
    "state": ["funds_received", "in_review"]
  },
  "event_created_at": "2025-07-22T11:35:00.000Z"
}

The outbound fiat payment to the destination has been submitted.

{
  "api_version": "v0",
  "event_id": "wh_d04submitted",
  "event_sequence": 4,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "liquidation_address.drain",
  "event_type": "liquidation_address.drain.updated.status_transitioned",
  "event_object_id": "drn_6b2c3d4e5f6a7b8c",
  "event_object_status": "payment_submitted",
  "event_object": {
    "id": "drn_6b2c3d4e5f6a7b8c",
    "customer_id": "cust_alice",
    "liquidation_address_id": "la_abc123def456",
    "amount": "250.00",
    "currency": "usdc",
    "state": "payment_submitted",
    "deposit_tx_hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab",
    "deposit_tx_timestamp": "2025-07-22T11:25:00.000Z",
    "from_address": "0x1111111111111111111111111111111111111111",
    "destination": {
      "payment_rail": "ach",
      "currency": "usd",
      "external_account_id": "external-account-123"
    },
    "created_at": "2025-07-22T11:26:00.000Z",
    "updated_at": "2025-07-22T12:00:00.000Z"
  },
  "event_object_changes": {
    "state": ["in_review", "payment_submitted"]
  },
  "event_created_at": "2025-07-22T12:00:00.000Z"
}

The drain has passed validation and is queued to be submitted.

{
  "api_version": "v0",
  "event_id": "wh_d05validated",
  "event_sequence": 5,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "liquidation_address.drain",
  "event_type": "liquidation_address.drain.updated.status_transitioned",
  "event_object_id": "drn_6b2c3d4e5f6a7b8c",
  "event_object_status": "payment_validated",
  "event_object": {
    "id": "drn_6b2c3d4e5f6a7b8c",
    "customer_id": "cust_alice",
    "liquidation_address_id": "la_abc123def456",
    "amount": "250.00",
    "currency": "usdc",
    "state": "payment_validated",
    "deposit_tx_hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab",
    "deposit_tx_timestamp": "2025-07-22T11:25:00.000Z",
    "from_address": "0x1111111111111111111111111111111111111111",
    "destination": {
      "payment_rail": "ach",
      "currency": "usd",
      "external_account_id": "external-account-123"
    },
    "created_at": "2025-07-22T11:26:00.000Z",
    "updated_at": "2025-07-23T08:00:00.000Z"
  },
  "event_object_changes": {
    "state": ["payment_submitted", "payment_validated"]
  },
  "event_created_at": "2025-07-23T08:00:00.000Z"
}

Terminal success. Funds have settled with the destination.

{
  "api_version": "v0",
  "event_id": "wh_d06processed",
  "event_sequence": 6,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "liquidation_address.drain",
  "event_type": "liquidation_address.drain.updated.status_transitioned",
  "event_object_id": "drn_6b2c3d4e5f6a7b8c",
  "event_object_status": "payment_processed",
  "event_object": {
    "id": "drn_6b2c3d4e5f6a7b8c",
    "customer_id": "cust_alice",
    "liquidation_address_id": "la_abc123def456",
    "amount": "250.00",
    "currency": "usdc",
    "state": "payment_processed",
    "deposit_tx_hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab",
    "deposit_tx_timestamp": "2025-07-22T11:25:00.000Z",
    "from_address": "0x1111111111111111111111111111111111111111",
    "destination": {
      "payment_rail": "ach",
      "currency": "usd",
      "external_account_id": "external-account-123"
    },
    "receipt": {
      "initial_amount": "250.00",
      "subtotal_amount": "250.00",
      "final_amount": "250.00"
    },
    "created_at": "2025-07-22T11:26:00.000Z",
    "updated_at": "2025-07-24T07:00:00.000Z"
  },
  "event_object_changes": {
    "state": ["payment_validated", "payment_processed"]
  },
  "event_created_at": "2025-07-24T07:00:00.000Z"
}

Blocked: the customer needs additional KYC before Bridge can process the drain. Note the extra kyc_link field, only present in this state.

{
  "api_version": "v0",
  "event_id": "wh_d07kycreq",
  "event_sequence": 2,
  "event_developer_id": "dev_222bbb333ccc444ddd",
  "event_category": "liquidation_address.drain",
  "event_type": "liquidation_address.drain.updated.status_transitioned",
  "event_object_id": "drn_7c3d4e5f6a7b8c9d",
  "event_object_status": "kyc_required",
  "event_object": {
    "id": "drn_7c3d4e5f6a7b8c9d",
    "customer_id": "cust_carol",
    "liquidation_address_id": "la_def456ghi789",
    "amount": "400.00",
    "currency": "usdc",
    "state": "kyc_required",
    "deposit_tx_hash": "0xbbcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab",
    "deposit_tx_timestamp": "2025-07-20T09:00:00.000Z",
    "from_address": "0x3333333333333333333333333333333333333333",
    "destination": {
      "payment_rail": "wire",
      "currency": "usd",
      "external_account_id": "external-account-456"
    },
    "kyc_link": "https://verify.bridge.xyz/kyc?token=def456",
    "created_at": "2025-07-20T09:00:00.000Z",
    "updated_at": "2025-07-20T09:05:00.000Z"
  },
  "event_object_changes": {
    "state": ["funds_received", "kyc_required"]
  },
  "event_created_at": "2025-07-20T09:05:00.000Z"
}

The customer submitted the requested KYC information; it’s under review.

{
  "api_version": "v0",
  "event_id": "wh_d08kycreview",
  "event_sequence": 3,
  "event_developer_id": "dev_222bbb333ccc444ddd",
  "event_category": "liquidation_address.drain",
  "event_type": "liquidation_address.drain.updated.status_transitioned",
  "event_object_id": "drn_7c3d4e5f6a7b8c9d",
  "event_object_status": "kyc_in_review",
  "event_object": {
    "id": "drn_7c3d4e5f6a7b8c9d",
    "customer_id": "cust_carol",
    "liquidation_address_id": "la_def456ghi789",
    "amount": "400.00",
    "currency": "usdc",
    "state": "kyc_in_review",
    "deposit_tx_hash": "0xbbcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab",
    "deposit_tx_timestamp": "2025-07-20T09:00:00.000Z",
    "from_address": "0x3333333333333333333333333333333333333333",
    "destination": {
      "payment_rail": "wire",
      "currency": "usd",
      "external_account_id": "external-account-456"
    },
    "created_at": "2025-07-20T09:00:00.000Z",
    "updated_at": "2025-07-20T15:30:00.000Z"
  },
  "event_object_changes": {
    "state": ["kyc_required", "kyc_in_review"]
  },
  "event_created_at": "2025-07-20T15:30:00.000Z"
}

Blocked: the developer’s own KYB must be completed before the drain can proceed.

{
  "api_version": "v0",
  "event_id": "wh_d09kybreq",
  "event_sequence": 2,
  "event_developer_id": "dev_333ccc444ddd555eee",
  "event_category": "liquidation_address.drain",
  "event_type": "liquidation_address.drain.updated.status_transitioned",
  "event_object_id": "drn_8d4e5f6a7b8c9d0e",
  "event_object_status": "developer_kyb_required",
  "event_object": {
    "id": "drn_8d4e5f6a7b8c9d0e",
    "customer_id": "cust_dave",
    "liquidation_address_id": "la_ghi789jkl012",
    "amount": "800.00",
    "currency": "usdc",
    "state": "developer_kyb_required",
    "deposit_tx_hash": "0xccdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab",
    "deposit_tx_timestamp": "2025-07-19T10:00:00.000Z",
    "from_address": "0x4444444444444444444444444444444444444444",
    "destination": {
      "payment_rail": "wire",
      "currency": "usd",
      "external_account_id": "external-account-789"
    },
    "created_at": "2025-07-19T10:00:00.000Z",
    "updated_at": "2025-07-19T10:01:00.000Z"
  },
  "event_object_changes": {
    "state": ["funds_received", "developer_kyb_required"]
  },
  "event_created_at": "2025-07-19T10:01:00.000Z"
}

The on-chain deposit received was less than the drain’s expected amount.

{
  "api_version": "v0",
  "event_id": "wh_d10underfunded",
  "event_sequence": 2,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "liquidation_address.drain",
  "event_type": "liquidation_address.drain.updated.status_transitioned",
  "event_object_id": "drn_9e5f6a7b8c9d0e1f",
  "event_object_status": "underfunded",
  "event_object": {
    "id": "drn_9e5f6a7b8c9d0e1f",
    "customer_id": "cust_erin",
    "liquidation_address_id": "la_jkl012mno345",
    "amount": "100.00",
    "currency": "usdc",
    "state": "underfunded",
    "deposit_tx_hash": "0xddef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab",
    "deposit_tx_timestamp": "2025-07-18T14:00:00.000Z",
    "from_address": "0x4444444444444444444444444444444444444444",
    "destination": {
      "payment_rail": "ach",
      "currency": "usd",
      "external_account_id": "external-account-321"
    },
    "created_at": "2025-07-18T14:00:00.000Z",
    "updated_at": "2025-07-18T14:20:00.000Z"
  },
  "event_object_changes": {
    "state": ["awaiting_funds", "underfunded"]
  },
  "event_created_at": "2025-07-18T14:20:00.000Z"
}

Blocked: no return policy is configured for this liquidation address, and one is required before Bridge can proceed or safely return funds.

{
  "api_version": "v0",
  "event_id": "wh_d11missingreturn",
  "event_sequence": 2,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "liquidation_address.drain",
  "event_type": "liquidation_address.drain.updated.status_transitioned",
  "event_object_id": "drn_0f6a7b8c9d0e1f2a",
  "event_object_status": "missing_return_policy",
  "event_object": {
    "id": "drn_0f6a7b8c9d0e1f2a",
    "customer_id": "cust_frank",
    "liquidation_address_id": "la_mno345pqr678",
    "amount": "350.00",
    "currency": "usdc",
    "state": "missing_return_policy",
    "deposit_tx_hash": "0xeedef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab",
    "deposit_tx_timestamp": "2025-07-17T08:00:00.000Z",
    "from_address": "0x5555555555555555555555555555555555555555",
    "destination": {
      "payment_rail": "ach",
      "currency": "usd",
      "external_account_id": "external-account-654"
    },
    "created_at": "2025-07-17T08:00:00.000Z",
    "updated_at": "2025-07-17T08:10:00.000Z"
  },
  "event_object_changes": {
    "state": ["funds_received", "missing_return_policy"]
  },
  "event_created_at": "2025-07-17T08:10:00.000Z"
}

The outbound payment to the destination could not be delivered.

{
  "api_version": "v0",
  "event_id": "wh_d12undeliverable",
  "event_sequence": 5,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "liquidation_address.drain",
  "event_type": "liquidation_address.drain.updated.status_transitioned",
  "event_object_id": "drn_1a7b8c9d0e1f2a3b",
  "event_object_status": "undeliverable",
  "event_object": {
    "id": "drn_1a7b8c9d0e1f2a3b",
    "customer_id": "cust_grace",
    "liquidation_address_id": "la_pqr678stu901",
    "amount": "600.00",
    "currency": "usdc",
    "state": "undeliverable",
    "deposit_tx_hash": "0xffdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab",
    "deposit_tx_timestamp": "2025-07-16T10:00:00.000Z",
    "from_address": "0x6666666666666666666666666666666666666666",
    "destination": {
      "payment_rail": "ach",
      "currency": "usd",
      "external_account_id": "external-account-987"
    },
    "undeliverable_reason_code": "account_closed",
    "created_at": "2025-07-16T10:00:00.000Z",
    "updated_at": "2025-07-16T12:00:00.000Z"
  },
  "event_object_changes": {
    "state": ["payment_submitted", "undeliverable"]
  },
  "event_created_at": "2025-07-16T12:00:00.000Z"
}

An unexpected processing error occurred. Bridge is investigating.

{
  "api_version": "v0",
  "event_id": "wh_d13error",
  "event_sequence": 4,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "liquidation_address.drain",
  "event_type": "liquidation_address.drain.updated.status_transitioned",
  "event_object_id": "drn_2b8c9d0e1f2a3b4c",
  "event_object_status": "error",
  "event_object": {
    "id": "drn_2b8c9d0e1f2a3b4c",
    "customer_id": "cust_henry",
    "liquidation_address_id": "la_stu901vwx234",
    "amount": "450.00",
    "currency": "usdc",
    "state": "error",
    "deposit_tx_hash": "0x11def1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab",
    "deposit_tx_timestamp": "2025-07-15T09:00:00.000Z",
    "from_address": "0x7777777777777777777777777777777777777777",
    "destination": {
      "payment_rail": "wire",
      "currency": "usd",
      "external_account_id": "external-account-852"
    },
    "created_at": "2025-07-15T09:00:00.000Z",
    "updated_at": "2025-07-15T09:45:00.000Z"
  },
  "event_object_changes": {
    "state": ["payment_submitted", "error"]
  },
  "event_created_at": "2025-07-15T09:45:00.000Z"
}

The drain was canceled before completion.

{
  "api_version": "v0",
  "event_id": "wh_d14canceled",
  "event_sequence": 2,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "liquidation_address.drain",
  "event_type": "liquidation_address.drain.updated.status_transitioned",
  "event_object_id": "drn_3c9d0e1f2a3b4c5d",
  "event_object_status": "canceled",
  "event_object": {
    "id": "drn_3c9d0e1f2a3b4c5d",
    "customer_id": "cust_iris",
    "liquidation_address_id": "la_vwx234yza567",
    "amount": "150.00",
    "currency": "usdc",
    "state": "canceled",
    "deposit_tx_hash": "0x22def1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab",
    "deposit_tx_timestamp": "2025-07-14T13:00:00.000Z",
    "from_address": "0x8888888888888888888888888888888888888888",
    "destination": {
      "payment_rail": "ach",
      "currency": "usd",
      "external_account_id": "external-account-741"
    },
    "created_at": "2025-07-14T13:00:00.000Z",
    "updated_at": "2025-07-14T13:05:00.000Z"
  },
  "event_object_changes": {
    "state": ["awaiting_funds", "canceled"]
  },
  "event_created_at": "2025-07-14T13:05:00.000Z"
}

The drain was deactivated and will no longer be processed.

{
  "api_version": "v0",
  "event_id": "wh_d15deactivated",
  "event_sequence": 2,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "liquidation_address.drain",
  "event_type": "liquidation_address.drain.updated.status_transitioned",
  "event_object_id": "drn_4d0e1f2a3b4c5d6e",
  "event_object_status": "deactivated",
  "event_object": {
    "id": "drn_4d0e1f2a3b4c5d6e",
    "customer_id": "cust_jack",
    "liquidation_address_id": "la_yza567bcd890",
    "amount": "250.00",
    "currency": "usdc",
    "state": "deactivated",
    "deposit_tx_hash": "0x33def1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab",
    "deposit_tx_timestamp": "2025-07-13T11:00:00.000Z",
    "from_address": "0x9999999999999999999999999999999999999999",
    "destination": {
      "payment_rail": "ach",
      "currency": "usd",
      "external_account_id": "external-account-963"
    },
    "created_at": "2025-07-13T11:00:00.000Z",
    "updated_at": "2025-07-13T11:30:00.000Z"
  },
  "event_object_changes": {
    "state": ["awaiting_funds", "deactivated"]
  },
  "event_created_at": "2025-07-13T11:30:00.000Z"
}

Funds were returned to the originating address instead of reaching the destination.

{
  "api_version": "v0",
  "event_id": "wh_d16returned",
  "event_sequence": 5,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "liquidation_address.drain",
  "event_type": "liquidation_address.drain.updated.status_transitioned",
  "event_object_id": "drn_1a7b8c9d0e1f2a3b",
  "event_object_status": "returned",
  "event_object": {
    "id": "drn_1a7b8c9d0e1f2a3b",
    "customer_id": "cust_grace",
    "liquidation_address_id": "la_pqr678stu901",
    "amount": "600.00",
    "currency": "usdc",
    "state": "returned",
    "deposit_tx_hash": "0xffdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab",
    "deposit_tx_timestamp": "2025-07-16T10:00:00.000Z",
    "from_address": "0x6666666666666666666666666666666666666666",
    "destination": {
      "payment_rail": "ach",
      "currency": "usd",
      "external_account_id": "external-account-987"
    },
    "return_details": {
      "reason": "undeliverable_destination",
      "amount": "600.00"
    },
    "created_at": "2025-07-16T10:00:00.000Z",
    "updated_at": "2025-07-16T18:00:00.000Z"
  },
  "event_object_changes": {
    "state": ["undeliverable", "returned"]
  },
  "event_created_at": "2025-07-16T18:00:00.000Z"
}

A refund of the original on-chain deposit has been initiated.

{
  "api_version": "v0",
  "event_id": "wh_d17refundinflight",
  "event_sequence": 6,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "liquidation_address.drain",
  "event_type": "liquidation_address.drain.updated.status_transitioned",
  "event_object_id": "drn_1a7b8c9d0e1f2a3b",
  "event_object_status": "refund_in_flight",
  "event_object": {
    "id": "drn_1a7b8c9d0e1f2a3b",
    "customer_id": "cust_grace",
    "liquidation_address_id": "la_pqr678stu901",
    "amount": "600.00",
    "currency": "usdc",
    "state": "refund_in_flight",
    "deposit_tx_hash": "0xffdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab",
    "deposit_tx_timestamp": "2025-07-16T10:00:00.000Z",
    "from_address": "0x6666666666666666666666666666666666666666",
    "destination": {
      "payment_rail": "ach",
      "currency": "usd",
      "external_account_id": "external-account-987"
    },
    "return_details": {
      "reason": "undeliverable_destination",
      "amount": "600.00"
    },
    "created_at": "2025-07-16T10:00:00.000Z",
    "updated_at": "2025-07-17T09:00:00.000Z"
  },
  "event_object_changes": {
    "state": ["returned", "refund_in_flight"]
  },
  "event_created_at": "2025-07-17T09:00:00.000Z"
}

Terminal: the refund completed and funds are back at the originating address.

{
  "api_version": "v0",
  "event_id": "wh_d18refunded",
  "event_sequence": 7,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "liquidation_address.drain",
  "event_type": "liquidation_address.drain.updated.status_transitioned",
  "event_object_id": "drn_1a7b8c9d0e1f2a3b",
  "event_object_status": "refunded",
  "event_object": {
    "id": "drn_1a7b8c9d0e1f2a3b",
    "customer_id": "cust_grace",
    "liquidation_address_id": "la_pqr678stu901",
    "amount": "600.00",
    "currency": "usdc",
    "state": "refunded",
    "deposit_tx_hash": "0xffdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab",
    "deposit_tx_timestamp": "2025-07-16T10:00:00.000Z",
    "from_address": "0x6666666666666666666666666666666666666666",
    "destination": {
      "payment_rail": "ach",
      "currency": "usd",
      "external_account_id": "external-account-987"
    },
    "return_details": {
      "reason": "undeliverable_destination",
      "amount": "600.00"
    },
    "refund_tx_hash": "0x44def1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab",
    "created_at": "2025-07-16T10:00:00.000Z",
    "updated_at": "2025-07-17T15:00:00.000Z"
  },
  "event_object_changes": {
    "state": ["refund_in_flight", "refunded"]
  },
  "event_created_at": "2025-07-17T15:00:00.000Z"
}

Terminal: the attempted refund did not succeed. Contact Bridge support to resolve.

{
  "api_version": "v0",
  "event_id": "wh_d19refundfailed",
  "event_sequence": 7,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "liquidation_address.drain",
  "event_type": "liquidation_address.drain.updated.status_transitioned",
  "event_object_id": "drn_5e1f2a3b4c5d6e7f",
  "event_object_status": "refund_failed",
  "event_object": {
    "id": "drn_5e1f2a3b4c5d6e7f",
    "customer_id": "cust_kate",
    "liquidation_address_id": "la_bcd890efg123",
    "amount": "200.00",
    "currency": "usdc",
    "state": "refund_failed",
    "deposit_tx_hash": "0x55def1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab",
    "deposit_tx_timestamp": "2025-07-12T10:00:00.000Z",
    "from_address": "0x1010101010101010101010101010101010101010",
    "destination": {
      "payment_rail": "ach",
      "currency": "usd",
      "external_account_id": "external-account-159"
    },
    "return_details": {
      "reason": "undeliverable_destination",
      "amount": "200.00"
    },
    "created_at": "2025-07-12T10:00:00.000Z",
    "updated_at": "2025-07-13T10:00:00.000Z"
  },
  "event_object_changes": {
    "state": ["refund_in_flight", "refund_failed"]
  },
  "event_created_at": "2025-07-13T10:00:00.000Z"
}

Card Accounts

status is one of active, pending, inactive, frozen (frozen can override any of the other three while a freeze is in effect). card_details, balances, cardholder_name, and funding instructions are only included once the account has finished provisioning and has at least one card issued against it — they are omitted for an account that hasn’t finished provisioning yet, or that was closed before any cards were issued.

pending
active
frozen
inactive

Card account created; still provisioning with the issuing vendor.

{
  "api_version": "v0",
  "event_id": "wh_ca01pending",
  "event_sequence": 1,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "card_account",
  "event_type": "card_account.created",
  "event_object_id": "ca_abc123def456",
  "event_object_status": null,
  "event_object": {
    "id": "ca_abc123def456",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "client_reference_id": "my-card-001",
    "status": "pending",
    "freezes": [],
    "created_at": "2025-01-15T10:30:00.000Z"
  },
  "event_object_changes": {},
  "event_created_at": "2025-01-15T10:30:00.000Z"
}

Provisioning completed. Card details, balances, and funding instructions are now present.

{
  "api_version": "v0",
  "event_id": "wh_ca02active",
  "event_sequence": 2,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "card_account",
  "event_type": "card_account.updated",
  "event_object_id": "ca_abc123def456",
  "event_object_status": null,
  "event_object": {
    "id": "ca_abc123def456",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "client_reference_id": "my-card-001",
    "status": "active",
    "freezes": [],
    "created_at": "2025-01-15T10:30:00.000Z",
    "card_details": {
      "last_4": "1234",
      "expiry": "12/27",
      "pin_status": "set",
      "bin": "411111"
    },
    "balances": {
      "available": {
        "amount": "250.00",
        "currency": "usd"
      },
      "hold": {
        "amount": "10.00",
        "currency": "usd"
      }
    },
    "cardholder_name": {
      "first_name": "John",
      "middle_name": null,
      "last_name": "Doe"
    }
  },
  "event_object_changes": {
    "status": ["pending", "active"]
  },
  "event_created_at": "2025-01-15T12:00:00.000Z"
}

A freeze is currently in effect on the account.

{
  "api_version": "v0",
  "event_id": "wh_ca03frozen",
  "event_sequence": 3,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "card_account",
  "event_type": "card_account.updated",
  "event_object_id": "ca_abc123def456",
  "event_object_status": null,
  "event_object": {
    "id": "ca_abc123def456",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "client_reference_id": "my-card-001",
    "status": "frozen",
    "freezes": [
      {
        "initiator": "developer",
        "reason": "suspected_fraud",
        "reason_detail": "Unusual spend pattern flagged by developer risk rules",
        "starting_at": "2025-01-16T09:00:00.000Z",
        "ending_at": null,
        "created_at": "2025-01-16T09:00:00.000Z"
      }
    ],
    "created_at": "2025-01-15T10:30:00.000Z",
    "card_details": {
      "last_4": "1234",
      "expiry": "12/27",
      "pin_status": "set",
      "bin": "411111"
    },
    "balances": {
      "available": {
        "amount": "250.00",
        "currency": "usd"
      },
      "hold": {
        "amount": "10.00",
        "currency": "usd"
      }
    },
    "cardholder_name": {
      "first_name": "John",
      "middle_name": null,
      "last_name": "Doe"
    }
  },
  "event_object_changes": {
    "status": ["active", "frozen"]
  },
  "event_created_at": "2025-01-16T09:00:00.000Z"
}

The account was closed by the customer or developer, or terminated by Bridge.

{
  "api_version": "v0",
  "event_id": "wh_ca04inactive",
  "event_sequence": 4,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "card_account",
  "event_type": "card_account.updated",
  "event_object_id": "ca_abc123def456",
  "event_object_status": null,
  "event_object": {
    "id": "ca_abc123def456",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "client_reference_id": "my-card-001",
    "status": "inactive",
    "freezes": [],
    "created_at": "2025-01-15T10:30:00.000Z",
    "card_details": {
      "last_4": "1234",
      "expiry": "12/27",
      "pin_status": "set",
      "bin": "411111"
    },
    "balances": {
      "available": {
        "amount": "0.00",
        "currency": "usd"
      },
      "hold": {
        "amount": "0.00",
        "currency": "usd"
      }
    },
    "cardholder_name": {
      "first_name": "John",
      "middle_name": null,
      "last_name": "Doe"
    }
  },
  "event_object_changes": {
    "status": ["active", "inactive"]
  },
  "event_created_at": "2025-01-20T10:00:00.000Z"
}

Card Transactions

Fires as a card transaction moves through authorization, capture, and settlement. status is one of approved, denied, expired, settled, merchant_credit_on_hold, incrementally_settled, reversed, partially_reversed, incremental_auth_approved. category is one of purchase, refund, adjustment, fee.

Authorization approved, transaction still open.

{
  "api_version": "v0",
  "event_id": "wh_ct01approved",
  "event_sequence": 1,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "card_transaction",
  "event_type": "card_transaction.created",
  "event_object_id": "ctx_abc123def456",
  "event_object_status": "approved",
  "event_object": {
    "id": "ctx_abc123def456",
    "card_account_id": "ca_abc123def456",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "amount": "42.50",
    "original_amount": "42.50",
    "billing_amount": "42.50",
    "currency": "usd",
    "category": "purchase",
    "status": "approved",
    "status_reason": "approved",
    "created_at": "2025-01-15T10:30:00.000Z",
    "authorized_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T10:30:00.000Z",
    "merchant_category_code": "5999",
    "merchant_name": "AMAZON.COM",
    "merchant_location": "SEATTLE, WA",
    "transaction_description": "AMAZON.COM Purchase",
    "authorization_infos": [],
    "risk_hold_release_at": null,
    "fees": null
  },
  "event_object_changes": {},
  "event_created_at": "2025-01-15T10:30:00.000Z"
}

Authorization denied by Bridge, the vendor, or the issuing network.

{
  "api_version": "v0",
  "event_id": "wh_ct02denied",
  "event_sequence": 1,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "card_transaction",
  "event_type": "card_transaction.created",
  "event_object_id": "ctx_bcd234efg567",
  "event_object_status": "denied",
  "event_object": {
    "id": "ctx_bcd234efg567",
    "card_account_id": "ca_abc123def456",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "amount": "500.00",
    "original_amount": "500.00",
    "billing_amount": "500.00",
    "currency": "usd",
    "category": "purchase",
    "status": "denied",
    "status_reason": "insufficient_funds",
    "created_at": "2025-01-15T11:00:00.000Z",
    "authorized_at": null,
    "updated_at": "2025-01-15T11:00:00.000Z",
    "merchant_category_code": "5311",
    "merchant_name": "BEST BUY",
    "merchant_location": "SEATTLE, WA",
    "transaction_description": "BEST BUY Purchase",
    "authorization_infos": [],
    "risk_hold_release_at": null,
    "fees": null
  },
  "event_object_changes": {},
  "event_created_at": "2025-01-15T11:00:00.000Z"
}

Authorization cleared and fully settled.

{
  "api_version": "v0",
  "event_id": "wh_ct03settled",
  "event_sequence": 2,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "card_transaction",
  "event_type": "card_transaction.updated",
  "event_object_id": "ctx_abc123def456",
  "event_object_status": "settled",
  "event_object": {
    "id": "ctx_abc123def456",
    "card_account_id": "ca_abc123def456",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "amount": "42.50",
    "original_amount": "42.50",
    "billing_amount": "42.50",
    "currency": "usd",
    "category": "purchase",
    "status": "settled",
    "status_reason": "approved",
    "created_at": "2025-01-15T10:30:00.000Z",
    "authorized_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-16T14:00:00.000Z",
    "merchant_category_code": "5999",
    "merchant_name": "AMAZON.COM",
    "merchant_location": "SEATTLE, WA",
    "transaction_description": "AMAZON.COM Purchase",
    "authorization_infos": [],
    "risk_hold_release_at": null,
    "fees": null
  },
  "event_object_changes": {
    "status": ["approved", "settled"]
  },
  "event_created_at": "2025-01-16T14:00:00.000Z"
}

Partial settlement has been applied; more settlement is still expected (e.g. hotel or car-rental incrementals).

{
  "api_version": "v0",
  "event_id": "wh_ct04incremental",
  "event_sequence": 2,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "card_transaction",
  "event_type": "card_transaction.updated",
  "event_object_id": "ctx_cde345fgh678",
  "event_object_status": "incrementally_settled",
  "event_object": {
    "id": "ctx_cde345fgh678",
    "card_account_id": "ca_abc123def456",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "amount": "150.00",
    "original_amount": "150.00",
    "billing_amount": "90.00",
    "currency": "usd",
    "category": "purchase",
    "status": "incrementally_settled",
    "status_reason": "approved",
    "created_at": "2025-01-14T18:00:00.000Z",
    "authorized_at": "2025-01-14T18:00:00.000Z",
    "updated_at": "2025-01-15T09:00:00.000Z",
    "merchant_category_code": "7011",
    "merchant_name": "HILTON HOTELS",
    "merchant_location": "AUSTIN, TX",
    "transaction_description": "HILTON HOTELS Purchase",
    "authorization_infos": [],
    "risk_hold_release_at": null,
    "fees": null
  },
  "event_object_changes": {
    "status": ["approved", "incrementally_settled"]
  },
  "event_created_at": "2025-01-15T09:00:00.000Z"
}

A merchant credit (refund-like) settlement is on hold pending risk review.

{
  "api_version": "v0",
  "event_id": "wh_ct05creditonhold",
  "event_sequence": 1,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "card_transaction",
  "event_type": "card_transaction.created",
  "event_object_id": "ctx_def456ghi789",
  "event_object_status": "merchant_credit_on_hold",
  "event_object": {
    "id": "ctx_def456ghi789",
    "card_account_id": "ca_abc123def456",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "amount": "-42.50",
    "original_amount": "-42.50",
    "billing_amount": "-42.50",
    "currency": "usd",
    "category": "refund",
    "status": "merchant_credit_on_hold",
    "status_reason": null,
    "created_at": "2025-01-17T10:00:00.000Z",
    "authorized_at": null,
    "updated_at": "2025-01-17T10:00:00.000Z",
    "merchant_category_code": "5999",
    "merchant_name": "AMAZON.COM",
    "merchant_location": "SEATTLE, WA",
    "transaction_description": "AMAZON.COM Refund",
    "authorization_infos": [],
    "risk_hold_release_at": "2025-01-20T10:00:00.000Z",
    "fees": null
  },
  "event_object_changes": {},
  "event_created_at": "2025-01-17T10:00:00.000Z"
}

Authorization fully reversed (voided) before settlement.

{
  "api_version": "v0",
  "event_id": "wh_ct06reversed",
  "event_sequence": 2,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "card_transaction",
  "event_type": "card_transaction.updated",
  "event_object_id": "ctx_efg567hij890",
  "event_object_status": "reversed",
  "event_object": {
    "id": "ctx_efg567hij890",
    "card_account_id": "ca_abc123def456",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "amount": "75.00",
    "original_amount": "75.00",
    "billing_amount": "75.00",
    "currency": "usd",
    "category": "purchase",
    "status": "reversed",
    "status_reason": "approved",
    "created_at": "2025-01-15T13:00:00.000Z",
    "authorized_at": "2025-01-15T13:00:00.000Z",
    "updated_at": "2025-01-15T13:30:00.000Z",
    "merchant_category_code": "5812",
    "merchant_name": "STARBUCKS",
    "merchant_location": "SEATTLE, WA",
    "transaction_description": "STARBUCKS Purchase",
    "authorization_infos": [],
    "risk_hold_release_at": null,
    "fees": null
  },
  "event_object_changes": {
    "status": ["approved", "reversed"]
  },
  "event_created_at": "2025-01-15T13:30:00.000Z"
}

Authorization partially reversed (e.g. a tip adjustment reducing the hold).

{
  "api_version": "v0",
  "event_id": "wh_ct07partialreversed",
  "event_sequence": 2,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "card_transaction",
  "event_type": "card_transaction.updated",
  "event_object_id": "ctx_fgh678ijk901",
  "event_object_status": "partially_reversed",
  "event_object": {
    "id": "ctx_fgh678ijk901",
    "card_account_id": "ca_abc123def456",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "amount": "60.00",
    "original_amount": "80.00",
    "billing_amount": "60.00",
    "currency": "usd",
    "category": "purchase",
    "status": "partially_reversed",
    "status_reason": "approved",
    "created_at": "2025-01-15T19:00:00.000Z",
    "authorized_at": "2025-01-15T19:00:00.000Z",
    "updated_at": "2025-01-15T19:45:00.000Z",
    "merchant_category_code": "5812",
    "merchant_name": "THE RESTAURANT",
    "merchant_location": "SEATTLE, WA",
    "transaction_description": "THE RESTAURANT Purchase",
    "authorization_infos": [],
    "risk_hold_release_at": null,
    "fees": null
  },
  "event_object_changes": {
    "amount": ["80.00", "60.00"]
  },
  "event_created_at": "2025-01-15T19:45:00.000Z"
}

An incremental authorization (adding to an existing hold) was approved.

{
  "api_version": "v0",
  "event_id": "wh_ct08incrementalauth",
  "event_sequence": 2,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "card_transaction",
  "event_type": "card_transaction.updated",
  "event_object_id": "ctx_cde345fgh678",
  "event_object_status": "incremental_auth_approved",
  "event_object": {
    "id": "ctx_cde345fgh678",
    "card_account_id": "ca_abc123def456",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "amount": "180.00",
    "original_amount": "150.00",
    "billing_amount": "180.00",
    "currency": "usd",
    "category": "purchase",
    "status": "incremental_auth_approved",
    "status_reason": "approved",
    "created_at": "2025-01-14T18:00:00.000Z",
    "authorized_at": "2025-01-14T18:00:00.000Z",
    "updated_at": "2025-01-14T20:00:00.000Z",
    "merchant_category_code": "7011",
    "merchant_name": "HILTON HOTELS",
    "merchant_location": "AUSTIN, TX",
    "transaction_description": "HILTON HOTELS Purchase",
    "authorization_infos": [],
    "risk_hold_release_at": null,
    "fees": null
  },
  "event_object_changes": {
    "amount": ["150.00", "180.00"]
  },
  "event_created_at": "2025-01-14T20:00:00.000Z"
}

Authorization hold expired before capture or reversal.

{
  "api_version": "v0",
  "event_id": "wh_ct09expired",
  "event_sequence": 2,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "card_transaction",
  "event_type": "card_transaction.updated",
  "event_object_id": "ctx_ghi789jkl012",
  "event_object_status": "expired",
  "event_object": {
    "id": "ctx_ghi789jkl012",
    "card_account_id": "ca_abc123def456",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "amount": "25.00",
    "original_amount": "25.00",
    "billing_amount": "25.00",
    "currency": "usd",
    "category": "purchase",
    "status": "expired",
    "status_reason": "approved",
    "created_at": "2025-01-10T08:00:00.000Z",
    "authorized_at": "2025-01-10T08:00:00.000Z",
    "updated_at": "2025-01-17T08:00:00.000Z",
    "merchant_category_code": "5541",
    "merchant_name": "SHELL GAS STATION",
    "merchant_location": "SEATTLE, WA",
    "transaction_description": "SHELL GAS STATION Purchase",
    "authorization_infos": [],
    "risk_hold_release_at": null,
    "fees": null
  },
  "event_object_changes": {
    "status": ["approved", "expired"]
  },
  "event_created_at": "2025-01-17T08:00:00.000Z"
}

Posted Card Account Transactions

Settled activity from the posted-transaction history feed. status is always posted — this category only ever fires created/updated, never updated.status_transitioned, since the public status does not change once posted. category is one of purchase, refund, adjustment, fee, crypto_funding, crypto_withdrawal, crypto_return.

{
  "api_version": "v0",
  "event_id": "wh_pt01purchase",
  "event_sequence": 1,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "posted_card_account_transaction",
  "event_type": "posted_card_account_transaction.created",
  "event_object_id": "ptx_abc123def456",
  "event_object_status": "posted",
  "event_object": {
    "id": "ptx_abc123def456",
    "card_account_id": "ca_abc123def456",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "amount": "42.50",
    "billing_amount": "42.50",
    "currency": "usd",
    "category": "purchase",
    "status": "posted",
    "posted_at": "2025-01-16T14:00:00.000Z",
    "created_at": "2025-01-15T10:30:00.000Z",
    "authorized_at": "2025-01-15T10:30:00.000Z",
    "merchant_category_code": "5999",
    "merchant_name": "AMAZON.COM",
    "merchant_location": "SEATTLE, WA",
    "description": "AMAZON.COM Purchase",
    "local_transaction_details": null,
    "crypto_transaction_details": null,
    "status_reason": null,
    "pagination_token": null,
    "related_transaction_ids": ["ctx_abc123def456"],
    "card_balance": "207.50",
    "source_id": null,
    "transaction_fee": null
  },
  "event_object_changes": {},
  "event_created_at": "2025-01-16T14:00:00.000Z"
}

{
  "api_version": "v0",
  "event_id": "wh_pt02refund",
  "event_sequence": 1,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "posted_card_account_transaction",
  "event_type": "posted_card_account_transaction.created",
  "event_object_id": "ptx_bcd234efg567",
  "event_object_status": "posted",
  "event_object": {
    "id": "ptx_bcd234efg567",
    "card_account_id": "ca_abc123def456",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "amount": "-42.50",
    "billing_amount": "-42.50",
    "currency": "usd",
    "category": "refund",
    "status": "posted",
    "posted_at": "2025-01-20T10:00:00.000Z",
    "created_at": "2025-01-20T10:00:00.000Z",
    "authorized_at": null,
    "merchant_category_code": "5999",
    "merchant_name": "AMAZON.COM",
    "merchant_location": "SEATTLE, WA",
    "description": "AMAZON.COM Refund",
    "local_transaction_details": null,
    "crypto_transaction_details": null,
    "status_reason": null,
    "pagination_token": null,
    "related_transaction_ids": ["ctx_def456ghi789"],
    "card_balance": "250.00",
    "source_id": null,
    "transaction_fee": null
  },
  "event_object_changes": {},
  "event_created_at": "2025-01-20T10:00:00.000Z"
}

{
  "api_version": "v0",
  "event_id": "wh_pt03adjustment",
  "event_sequence": 1,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "posted_card_account_transaction",
  "event_type": "posted_card_account_transaction.created",
  "event_object_id": "ptx_cde345fgh678",
  "event_object_status": "posted",
  "event_object": {
    "id": "ptx_cde345fgh678",
    "card_account_id": "ca_abc123def456",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "amount": "-15.00",
    "billing_amount": "-15.00",
    "currency": "usd",
    "category": "adjustment",
    "status": "posted",
    "posted_at": "2025-01-21T09:00:00.000Z",
    "created_at": "2025-01-21T09:00:00.000Z",
    "authorized_at": null,
    "merchant_category_code": null,
    "merchant_name": null,
    "merchant_location": null,
    "description": "Chargeback adjustment",
    "local_transaction_details": null,
    "crypto_transaction_details": null,
    "status_reason": null,
    "pagination_token": null,
    "related_transaction_ids": [],
    "card_balance": "235.00",
    "source_id": null,
    "transaction_fee": null
  },
  "event_object_changes": {},
  "event_created_at": "2025-01-21T09:00:00.000Z"
}

{
  "api_version": "v0",
  "event_id": "wh_pt04fee",
  "event_sequence": 1,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "posted_card_account_transaction",
  "event_type": "posted_card_account_transaction.created",
  "event_object_id": "ptx_def456ghi789",
  "event_object_status": "posted",
  "event_object": {
    "id": "ptx_def456ghi789",
    "card_account_id": "ca_abc123def456",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "amount": "-2.50",
    "billing_amount": "-2.50",
    "currency": "usd",
    "category": "fee",
    "status": "posted",
    "posted_at": "2025-01-22T00:00:00.000Z",
    "created_at": "2025-01-22T00:00:00.000Z",
    "authorized_at": null,
    "merchant_category_code": null,
    "merchant_name": null,
    "merchant_location": null,
    "description": "Monthly card fee",
    "local_transaction_details": null,
    "crypto_transaction_details": null,
    "status_reason": null,
    "pagination_token": null,
    "related_transaction_ids": [],
    "card_balance": "232.50",
    "source_id": null,
    "transaction_fee": null
  },
  "event_object_changes": {},
  "event_created_at": "2025-01-22T00:00:00.000Z"
}

{
  "api_version": "v0",
  "event_id": "wh_pt05cryptofunding",
  "event_sequence": 1,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "posted_card_account_transaction",
  "event_type": "posted_card_account_transaction.created",
  "event_object_id": "ptx_efg567hij890",
  "event_object_status": "posted",
  "event_object": {
    "id": "ptx_efg567hij890",
    "card_account_id": "ca_abc123def456",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "amount": "100.00",
    "billing_amount": "100.00",
    "currency": "usd",
    "category": "crypto_funding",
    "status": "posted",
    "posted_at": "2025-01-15T08:00:00.000Z",
    "created_at": "2025-01-15T08:00:00.000Z",
    "authorized_at": null,
    "merchant_category_code": null,
    "merchant_name": null,
    "merchant_location": null,
    "description": "Wallet top-up",
    "local_transaction_details": null,
    "crypto_transaction_details": {
      "from_address": "0x1111111111111111111111111111111111111111",
      "to_address": "0x2222222222222222222222222222222222222222",
      "tx_hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab",
      "chain": "ethereum",
      "memo": null
    },
    "status_reason": null,
    "pagination_token": null,
    "related_transaction_ids": [],
    "card_balance": "332.50",
    "source_id": null,
    "transaction_fee": null
  },
  "event_object_changes": {},
  "event_created_at": "2025-01-15T08:00:00.000Z"
}

{
  "api_version": "v0",
  "event_id": "wh_pt06cryptowithdrawal",
  "event_sequence": 1,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "posted_card_account_transaction",
  "event_type": "posted_card_account_transaction.created",
  "event_object_id": "ptx_fgh678ijk901",
  "event_object_status": "posted",
  "event_object": {
    "id": "ptx_fgh678ijk901",
    "card_account_id": "ca_abc123def456",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "amount": "-100.00",
    "billing_amount": "-100.00",
    "currency": "usd",
    "category": "crypto_withdrawal",
    "status": "posted",
    "posted_at": "2025-01-18T11:00:00.000Z",
    "created_at": "2025-01-18T11:00:00.000Z",
    "authorized_at": null,
    "merchant_category_code": null,
    "merchant_name": null,
    "merchant_location": null,
    "description": "Withdrawal to external wallet",
    "local_transaction_details": null,
    "crypto_transaction_details": {
      "from_address": "0x2222222222222222222222222222222222222222",
      "to_address": "0x3333333333333333333333333333333333333333",
      "tx_hash": "0xbcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abc",
      "chain": "ethereum",
      "memo": null
    },
    "status_reason": null,
    "pagination_token": null,
    "related_transaction_ids": [],
    "card_balance": "232.50",
    "source_id": null,
    "transaction_fee": null
  },
  "event_object_changes": {},
  "event_created_at": "2025-01-18T11:00:00.000Z"
}

{
  "api_version": "v0",
  "event_id": "wh_pt07cryptoreturn",
  "event_sequence": 1,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "posted_card_account_transaction",
  "event_type": "posted_card_account_transaction.created",
  "event_object_id": "ptx_ghi789jkl012",
  "event_object_status": "posted",
  "event_object": {
    "id": "ptx_ghi789jkl012",
    "card_account_id": "ca_abc123def456",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "amount": "40.00",
    "billing_amount": "40.00",
    "currency": "usd",
    "category": "crypto_return",
    "status": "posted",
    "posted_at": "2025-01-19T15:00:00.000Z",
    "created_at": "2025-01-19T15:00:00.000Z",
    "authorized_at": null,
    "merchant_category_code": null,
    "merchant_name": null,
    "merchant_location": null,
    "description": "Returned unused crypto funding",
    "local_transaction_details": null,
    "crypto_transaction_details": null,
    "status_reason": null,
    "pagination_token": null,
    "related_transaction_ids": ["ctx_cde345fgh678"],
    "card_balance": "272.50",
    "source_id": null,
    "transaction_fee": null
  },
  "event_object_changes": {},
  "event_created_at": "2025-01-19T15:00:00.000Z"
}

Card Withdrawals

status is one of pending, in_review, in_progress, completed, failed. type is top_up_balance_withdrawal or fee.

pending
in_review
in_progress
completed
failed

{
  "api_version": "v0",
  "event_id": "wh_cw01pending",
  "event_sequence": 1,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "card_withdrawal",
  "event_type": "card_withdrawal.created",
  "event_object_id": "cw_abc123def456",
  "event_object_status": "pending",
  "event_object": {
    "id": "cw_abc123def456",
    "card_account_id": "ca_abc123def456",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "amount": "100.00",
    "currency": "usdc",
    "status": "pending",
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T10:30:00.000Z",
    "destination": {
      "chain": "ethereum",
      "address": "0x1234567890abcdef1234567890abcdef12345678",
      "memo": null,
      "tx_hash": null,
      "gas_fee": null
    },
    "type": "top_up_balance_withdrawal",
    "client_note": null
  },
  "event_object_changes": {},
  "event_created_at": "2025-01-15T10:30:00.000Z"
}

AML screening is in progress.

{
  "api_version": "v0",
  "event_id": "wh_cw02inreview",
  "event_sequence": 2,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "card_withdrawal",
  "event_type": "card_withdrawal.updated",
  "event_object_id": "cw_abc123def456",
  "event_object_status": "in_review",
  "event_object": {
    "id": "cw_abc123def456",
    "card_account_id": "ca_abc123def456",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "amount": "100.00",
    "currency": "usdc",
    "status": "in_review",
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T10:31:00.000Z",
    "destination": {
      "chain": "ethereum",
      "address": "0x1234567890abcdef1234567890abcdef12345678",
      "memo": null,
      "tx_hash": null,
      "gas_fee": null
    },
    "type": "top_up_balance_withdrawal",
    "client_note": null
  },
  "event_object_changes": {
    "status": ["pending", "in_review"]
  },
  "event_created_at": "2025-01-15T10:31:00.000Z"
}

Screening passed; the on-chain withdrawal trip is underway.

{
  "api_version": "v0",
  "event_id": "wh_cw03inprogress",
  "event_sequence": 3,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "card_withdrawal",
  "event_type": "card_withdrawal.updated",
  "event_object_id": "cw_abc123def456",
  "event_object_status": "in_progress",
  "event_object": {
    "id": "cw_abc123def456",
    "card_account_id": "ca_abc123def456",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "amount": "100.00",
    "currency": "usdc",
    "status": "in_progress",
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T10:35:00.000Z",
    "destination": {
      "chain": "ethereum",
      "address": "0x1234567890abcdef1234567890abcdef12345678",
      "memo": null,
      "tx_hash": null,
      "gas_fee": null
    },
    "type": "top_up_balance_withdrawal",
    "client_note": null
  },
  "event_object_changes": {
    "status": ["in_review", "in_progress"]
  },
  "event_created_at": "2025-01-15T10:35:00.000Z"
}

Terminal success, with the on-chain transaction hash and gas fee now present.

{
  "api_version": "v0",
  "event_id": "wh_cw04completed",
  "event_sequence": 4,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "card_withdrawal",
  "event_type": "card_withdrawal.updated",
  "event_object_id": "cw_abc123def456",
  "event_object_status": "completed",
  "event_object": {
    "id": "cw_abc123def456",
    "card_account_id": "ca_abc123def456",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "amount": "100.00",
    "currency": "usdc",
    "status": "completed",
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T11:00:00.000Z",
    "destination": {
      "chain": "ethereum",
      "address": "0x1234567890abcdef1234567890abcdef12345678",
      "memo": null,
      "tx_hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab",
      "gas_fee": {
        "amount": "0.50",
        "currency": "usdc"
      }
    },
    "type": "top_up_balance_withdrawal",
    "client_note": null
  },
  "event_object_changes": {
    "status": ["in_progress", "completed"]
  },
  "event_created_at": "2025-01-15T11:00:00.000Z"
}

The withdrawal (or its underlying trip) failed, including rollback states.

{
  "api_version": "v0",
  "event_id": "wh_cw05failed",
  "event_sequence": 4,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "card_withdrawal",
  "event_type": "card_withdrawal.updated",
  "event_object_id": "cw_bcd234efg567",
  "event_object_status": "failed",
  "event_object": {
    "id": "cw_bcd234efg567",
    "card_account_id": "ca_abc123def456",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "amount": "50.00",
    "currency": "usdc",
    "status": "failed",
    "created_at": "2025-01-16T09:00:00.000Z",
    "updated_at": "2025-01-16T09:30:00.000Z",
    "destination": {
      "chain": "ethereum",
      "address": "0x1234567890abcdef1234567890abcdef12345678",
      "memo": null,
      "tx_hash": null,
      "gas_fee": null
    },
    "type": "fee",
    "client_note": null
  },
  "event_object_changes": {
    "status": ["in_progress", "failed"]
  },
  "event_created_at": "2025-01-16T09:30:00.000Z"
}

Virtual Account Activity

type is one of funding, drain, microdeposit, account_update, refund_in_flight, refund, refund_failed, in_review, payment_processed, deactivation, activation, funds_scheduled, close.

An incoming fiat deposit was received and converted to the destination asset.

{
  "api_version": "v0",
  "event_id": "wh_va01funding",
  "event_sequence": 1,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "virtual_account.activity",
  "event_type": "virtual_account.activity.created",
  "event_object_id": "fie_abc123def456",
  "event_object_status": null,
  "event_object": {
    "id": "fie_abc123def456",
    "type": "funding",
    "currency": "usd",
    "created_at": "2025-01-15T10:30:00.000Z",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "virtual_account_id": "va_def456abc789",
    "amount": "500.00",
    "developer_fee_amount": "5.00",
    "exchange_fee_amount": "0.00",
    "subtotal_amount": "495.00",
    "destination_payment_rail": "ethereum",
    "receipt": {
      "initial_amount": "500.00",
      "developer_fee": "5.00",
      "exchange_fee": "0.00",
      "subtotal_amount": "495.00",
      "final_amount": "495.00"
    },
    "source": {
      "payment_rail": "ach_push",
      "description": "ACH deposit",
      "sender_name": "John Doe",
      "trace_number": "091000019012345",
      "recipient_name": "Jane Smith"
    }
  },
  "event_object_changes": {},
  "event_created_at": "2025-01-15T10:30:00.000Z"
}

The incoming deposit was flagged for manual compliance review.

{
  "api_version": "v0",
  "event_id": "wh_va02inreview",
  "event_sequence": 1,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "virtual_account.activity",
  "event_type": "virtual_account.activity.created",
  "event_object_id": "fie_bcd234efg567",
  "event_object_status": null,
  "event_object": {
    "id": "fie_bcd234efg567",
    "type": "in_review",
    "currency": "usd",
    "created_at": "2025-01-16T08:00:00.000Z",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "virtual_account_id": "va_def456abc789",
    "amount": "10000.00",
    "developer_fee_amount": "100.00",
    "exchange_fee_amount": "0.00",
    "subtotal_amount": "9900.00",
    "destination_payment_rail": "ethereum",
    "source": {
      "payment_rail": "wire",
      "description": "Wire deposit",
      "sender_name": "Acme Corp",
      "trace_number": "WIRE09876543",
      "recipient_name": "Jane Smith"
    }
  },
  "event_object_changes": {},
  "event_created_at": "2025-01-16T08:00:00.000Z"
}

Review cleared and the deposit has been processed to the destination.

{
  "api_version": "v0",
  "event_id": "wh_va03processed",
  "event_sequence": 2,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "virtual_account.activity",
  "event_type": "virtual_account.activity.created",
  "event_object_id": "fie_cde345fgh678",
  "event_object_status": null,
  "event_object": {
    "id": "fie_cde345fgh678",
    "type": "payment_processed",
    "currency": "usd",
    "created_at": "2025-01-16T14:00:00.000Z",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "virtual_account_id": "va_def456abc789",
    "amount": "10000.00",
    "developer_fee_amount": "100.00",
    "exchange_fee_amount": "0.00",
    "subtotal_amount": "9900.00",
    "destination_payment_rail": "ethereum",
    "receipt": {
      "initial_amount": "10000.00",
      "developer_fee": "100.00",
      "exchange_fee": "0.00",
      "subtotal_amount": "9900.00",
      "final_amount": "9900.00"
    },
    "source": {
      "payment_rail": "wire",
      "description": "Wire deposit",
      "sender_name": "Acme Corp",
      "trace_number": "WIRE09876543",
      "recipient_name": "Jane Smith"
    }
  },
  "event_object_changes": {},
  "event_created_at": "2025-01-16T14:00:00.000Z"
}

A small verification deposit was received during virtual account setup.

{
  "api_version": "v0",
  "event_id": "wh_va04microdeposit",
  "event_sequence": 1,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "virtual_account.activity",
  "event_type": "virtual_account.activity.created",
  "event_object_id": "fie_def456ghi789",
  "event_object_status": null,
  "event_object": {
    "id": "fie_def456ghi789",
    "type": "microdeposit",
    "currency": "usd",
    "created_at": "2025-01-10T09:00:00.000Z",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "virtual_account_id": "va_def456abc789",
    "amount": "0.01",
    "developer_fee_amount": "0.00",
    "exchange_fee_amount": "0.00",
    "subtotal_amount": "0.01",
    "destination_payment_rail": "ethereum",
    "source": {
      "payment_rail": "ach_push",
      "description": "Verification microdeposit",
      "sender_name": "Bridge",
      "trace_number": "091000019000001",
      "recipient_name": "Jane Smith"
    }
  },
  "event_object_changes": {},
  "event_created_at": "2025-01-10T09:00:00.000Z"
}

The virtual account’s underlying bank account details were updated.

{
  "api_version": "v0",
  "event_id": "wh_va05accountupdate",
  "event_sequence": 1,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "virtual_account.activity",
  "event_type": "virtual_account.activity.created",
  "event_object_id": "fie_efg567hij890",
  "event_object_status": null,
  "event_object": {
    "id": "fie_efg567hij890",
    "type": "account_update",
    "currency": "usd",
    "created_at": "2025-01-12T10:00:00.000Z",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "virtual_account_id": "va_def456abc789",
    "amount": "0.00",
    "developer_fee_amount": "0.00",
    "exchange_fee_amount": "0.00",
    "subtotal_amount": "0.00",
    "destination_payment_rail": "ethereum"
  },
  "event_object_changes": {},
  "event_created_at": "2025-01-12T10:00:00.000Z"
}

The virtual account was activated and can now receive deposits.

{
  "api_version": "v0",
  "event_id": "wh_va06activation",
  "event_sequence": 1,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "virtual_account.activity",
  "event_type": "virtual_account.activity.created",
  "event_object_id": "fie_fgh678ijk901",
  "event_object_status": null,
  "event_object": {
    "id": "fie_fgh678ijk901",
    "type": "activation",
    "currency": "usd",
    "created_at": "2025-01-09T09:00:00.000Z",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "virtual_account_id": "va_def456abc789",
    "amount": "0.00",
    "developer_fee_amount": "0.00",
    "exchange_fee_amount": "0.00",
    "subtotal_amount": "0.00",
    "destination_payment_rail": "ethereum"
  },
  "event_object_changes": {},
  "event_created_at": "2025-01-09T09:00:00.000Z"
}

An incoming payment has been scheduled but has not yet settled (e.g. a future-dated ACH).

{
  "api_version": "v0",
  "event_id": "wh_va07fundsscheduled",
  "event_sequence": 1,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "virtual_account.activity",
  "event_type": "virtual_account.activity.created",
  "event_object_id": "fie_ghi789jkl012",
  "event_object_status": null,
  "event_object": {
    "id": "fie_ghi789jkl012",
    "type": "funds_scheduled",
    "currency": "usd",
    "created_at": "2025-01-18T10:00:00.000Z",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "virtual_account_id": "va_def456abc789",
    "amount": "1200.00",
    "developer_fee_amount": "12.00",
    "exchange_fee_amount": "0.00",
    "subtotal_amount": "1188.00",
    "destination_payment_rail": "ethereum",
    "source": {
      "payment_rail": "ach_push",
      "description": "Scheduled ACH deposit",
      "sender_name": "John Doe",
      "trace_number": "091000019012399",
      "recipient_name": "Jane Smith"
    }
  },
  "event_object_changes": {},
  "event_created_at": "2025-01-18T10:00:00.000Z"
}

Funds held at the virtual account were drained out to the destination.

{
  "api_version": "v0",
  "event_id": "wh_va08drain",
  "event_sequence": 1,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "virtual_account.activity",
  "event_type": "virtual_account.activity.created",
  "event_object_id": "fie_hij890klm123",
  "event_object_status": null,
  "event_object": {
    "id": "fie_hij890klm123",
    "type": "drain",
    "currency": "usd",
    "created_at": "2025-01-19T11:00:00.000Z",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "virtual_account_id": "va_def456abc789",
    "amount": "300.00",
    "developer_fee_amount": "3.00",
    "exchange_fee_amount": "0.00",
    "subtotal_amount": "297.00",
    "destination_payment_rail": "ethereum",
    "receipt": {
      "initial_amount": "300.00",
      "developer_fee": "3.00",
      "exchange_fee": "0.00",
      "subtotal_amount": "297.00",
      "final_amount": "297.00"
    }
  },
  "event_object_changes": {},
  "event_created_at": "2025-01-19T11:00:00.000Z"
}

A refund of a prior deposit is underway.

{
  "api_version": "v0",
  "event_id": "wh_va09refundinflight",
  "event_sequence": 2,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "virtual_account.activity",
  "event_type": "virtual_account.activity.created",
  "event_object_id": "fie_ijk901lmn234",
  "event_object_status": null,
  "event_object": {
    "id": "fie_ijk901lmn234",
    "type": "refund_in_flight",
    "currency": "usd",
    "created_at": "2025-01-20T09:00:00.000Z",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "virtual_account_id": "va_def456abc789",
    "amount": "500.00",
    "developer_fee_amount": "0.00",
    "exchange_fee_amount": "0.00",
    "subtotal_amount": "500.00",
    "destination_payment_rail": "ethereum",
    "source": {
      "payment_rail": "ach_push",
      "description": "ACH deposit",
      "sender_name": "John Doe",
      "trace_number": "091000019012345",
      "recipient_name": "Jane Smith"
    }
  },
  "event_object_changes": {},
  "event_created_at": "2025-01-20T09:00:00.000Z"
}

The refund completed successfully.

{
  "api_version": "v0",
  "event_id": "wh_va10refund",
  "event_sequence": 3,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "virtual_account.activity",
  "event_type": "virtual_account.activity.created",
  "event_object_id": "fie_jkl012mno345",
  "event_object_status": null,
  "event_object": {
    "id": "fie_jkl012mno345",
    "type": "refund",
    "currency": "usd",
    "created_at": "2025-01-20T15:00:00.000Z",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "virtual_account_id": "va_def456abc789",
    "amount": "500.00",
    "developer_fee_amount": "0.00",
    "exchange_fee_amount": "0.00",
    "subtotal_amount": "500.00",
    "destination_payment_rail": "ethereum",
    "source": {
      "payment_rail": "ach_push",
      "description": "ACH deposit",
      "sender_name": "John Doe",
      "trace_number": "091000019012345",
      "recipient_name": "Jane Smith"
    }
  },
  "event_object_changes": {},
  "event_created_at": "2025-01-20T15:00:00.000Z"
}

The attempted refund did not succeed.

{
  "api_version": "v0",
  "event_id": "wh_va11refundfailed",
  "event_sequence": 3,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "virtual_account.activity",
  "event_type": "virtual_account.activity.created",
  "event_object_id": "fie_klm123nop456",
  "event_object_status": null,
  "event_object": {
    "id": "fie_klm123nop456",
    "type": "refund_failed",
    "currency": "usd",
    "created_at": "2025-01-21T09:00:00.000Z",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "virtual_account_id": "va_def456abc789",
    "amount": "250.00",
    "developer_fee_amount": "0.00",
    "exchange_fee_amount": "0.00",
    "subtotal_amount": "250.00",
    "destination_payment_rail": "ethereum",
    "source": {
      "payment_rail": "ach_push",
      "description": "ACH deposit",
      "sender_name": "John Doe",
      "trace_number": "091000019012340",
      "recipient_name": "Jane Smith"
    }
  },
  "event_object_changes": {},
  "event_created_at": "2025-01-21T09:00:00.000Z"
}

The virtual account was deactivated and will no longer accept deposits.

{
  "api_version": "v0",
  "event_id": "wh_va12deactivation",
  "event_sequence": 1,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "virtual_account.activity",
  "event_type": "virtual_account.activity.created",
  "event_object_id": "fie_lmn234opq567",
  "event_object_status": null,
  "event_object": {
    "id": "fie_lmn234opq567",
    "type": "deactivation",
    "currency": "usd",
    "created_at": "2025-01-22T09:00:00.000Z",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "virtual_account_id": "va_def456abc789",
    "amount": "0.00",
    "developer_fee_amount": "0.00",
    "exchange_fee_amount": "0.00",
    "subtotal_amount": "0.00",
    "destination_payment_rail": "ethereum"
  },
  "event_object_changes": {},
  "event_created_at": "2025-01-22T09:00:00.000Z"
}

The virtual account was closed.

{
  "api_version": "v0",
  "event_id": "wh_va13close",
  "event_sequence": 1,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "virtual_account.activity",
  "event_type": "virtual_account.activity.created",
  "event_object_id": "fie_mno345pqr678",
  "event_object_status": null,
  "event_object": {
    "id": "fie_mno345pqr678",
    "type": "close",
    "currency": "usd",
    "created_at": "2025-01-25T09:00:00.000Z",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "virtual_account_id": "va_def456abc789",
    "amount": "0.00",
    "developer_fee_amount": "0.00",
    "exchange_fee_amount": "0.00",
    "subtotal_amount": "0.00",
    "destination_payment_rail": "ethereum"
  },
  "event_object_changes": {},
  "event_created_at": "2025-01-25T09:00:00.000Z"
}

Static Memo Activity

Behaves the same as Virtual Account Activity, but the deposit product is a static memo rather than a dedicated bank account: the object carries static_memo_id instead of virtual_account_id, and the source side carries a source_deposit_instructions.deposit_message (the memo string) rather than bank-transfer source fields. Only the two most common cases are shown here — every type value from the Virtual Account Activity section above applies equally.

funding
microdeposit

{
  "api_version": "v0",
  "event_id": "wh_sm01funding",
  "event_sequence": 1,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "static_memo.activity",
  "event_type": "static_memo.activity.created",
  "event_object_id": "fie_nop456qrs789",
  "event_object_status": null,
  "event_object": {
    "id": "fie_nop456qrs789",
    "type": "funding",
    "currency": "usd",
    "created_at": "2025-01-15T10:30:00.000Z",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "static_memo_id": "sm_abc123def456",
    "amount": "500.00",
    "developer_fee_amount": "5.00",
    "exchange_fee_amount": "0.00",
    "subtotal_amount": "495.00",
    "destination_payment_rail": "ethereum",
    "receipt": {
      "initial_amount": "500.00",
      "developer_fee": "5.00",
      "exchange_fee": "0.00",
      "subtotal_amount": "495.00",
      "final_amount": "495.00"
    },
    "source_deposit_instructions": {
      "deposit_message": "BRIDGE-ABC123"
    }
  },
  "event_object_changes": {},
  "event_created_at": "2025-01-15T10:30:00.000Z"
}

{
  "api_version": "v0",
  "event_id": "wh_sm02microdeposit",
  "event_sequence": 1,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "static_memo.activity",
  "event_type": "static_memo.activity.created",
  "event_object_id": "fie_ghi789jkl012",
  "event_object_status": null,
  "event_object": {
    "id": "fie_ghi789jkl012",
    "type": "microdeposit",
    "currency": "usd",
    "created_at": "2025-01-15T10:30:00.000Z",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "static_memo_id": "sm_abc123def456",
    "amount": "0.01",
    "developer_fee_amount": "0.00",
    "exchange_fee_amount": "0.00",
    "subtotal_amount": "0.01",
    "destination_payment_rail": "ethereum",
    "source_deposit_instructions": {
      "deposit_message": "BRIDGE-ABC123"
    }
  },
  "event_object_changes": {},
  "event_created_at": "2025-01-15T10:30:00.000Z"
}

External Accounts

External bank account linked to a customer. For webhook rendering, address and account_owner_country are deliberately excluded (they are included in API responses but not webhooks).

created
updated
deleted

{
  "api_version": "v0",
  "event_id": "wh_ea01created",
  "event_sequence": 1,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "external_account",
  "event_type": "external_account.created",
  "event_object_id": "ea_abc123def456",
  "event_object_status": null,
  "event_object": {
    "id": "ea_abc123def456",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T10:30:00.000Z",
    "bank_name": "Chase",
    "account_name": "Checking",
    "account_owner_name": "John Doe",
    "active": true,
    "currency": "usd",
    "account_owner_type": "individual",
    "account_type": "us",
    "first_name": "John",
    "last_name": "Doe",
    "business_name": null,
    "account": {
      "last_4": "4567",
      "routing_number": "110000000"
    },
    "beneficiary_address_valid": true,
    "last_4": "4567"
  },
  "event_object_changes": {},
  "event_created_at": "2025-01-15T10:30:00.000Z"
}

{
  "api_version": "v0",
  "event_id": "wh_ea02updated",
  "event_sequence": 2,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "external_account",
  "event_type": "external_account.updated",
  "event_object_id": "ea_abc123def456",
  "event_object_status": null,
  "event_object": {
    "id": "ea_abc123def456",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-20T09:00:00.000Z",
    "bank_name": "Chase",
    "account_name": "Primary Checking",
    "account_owner_name": "John Doe",
    "active": true,
    "currency": "usd",
    "account_owner_type": "individual",
    "account_type": "us",
    "first_name": "John",
    "last_name": "Doe",
    "business_name": null,
    "account": {
      "last_4": "4567",
      "routing_number": "110000000"
    },
    "beneficiary_address_valid": true,
    "last_4": "4567"
  },
  "event_object_changes": {
    "account_name": ["Checking", "Primary Checking"]
  },
  "event_created_at": "2025-01-20T09:00:00.000Z"
}

{
  "api_version": "v0",
  "event_id": "wh_ea03deleted",
  "event_sequence": 3,
  "event_developer_id": "dev_111aaa222bbb333ccc",
  "event_category": "external_account",
  "event_type": "external_account.deleted",
  "event_object_id": "ea_abc123def456",
  "event_object_status": null,
  "event_object": {
    "id": "ea_abc123def456",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-25T11:00:00.000Z",
    "bank_name": "Chase",
    "account_name": "Primary Checking",
    "account_owner_name": "John Doe",
    "active": false,
    "currency": "usd",
    "account_owner_type": "individual",
    "account_type": "us",
    "first_name": "John",
    "last_name": "Doe",
    "business_name": null,
    "account": {
      "last_4": "4567",
      "routing_number": "110000000"
    },
    "beneficiary_address_valid": true,
    "last_4": "4567"
  },
  "event_object_changes": {
    "active": [true, false]
  },
  "event_created_at": "2025-01-25T11:00:00.000Z"
}

Customers

created
updated.status_transitioned (incomplete)
updated.status_transitioned (awaiting_questionnaire)
updated.status_transitioned (awaiting_ubo)
updated.status_transitioned (under_review)
updated.status_transitioned (approved)
updated.status_transitioned (rejected)
updated.status_transitioned (paused)
updated.status_transitioned (deposits_restricted)
updated.status_transitioned (offboarded)
updated (non-status field)
deleted

{
  "api_version": "v0",
  "event_id": "wh_c1a2b3c4d5e6f708",
  "event_sequence": 1,
  "event_developer_id": "dev_1a2b3c4d5e6f7081",
  "event_category": "customer",
  "event_type": "customer.created",
  "event_object_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
  "event_object_status": "not_started",
  "event_object": {
    "id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "status": "not_started",
    "type": "individual",
    "persona_inquiry_type": "standard",
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T10:30:00.000Z",
    "rejection_reasons": [],
    "has_accepted_terms_of_service": false,
    "endorsements": [],
    "future_requirements_due": [],
    "requirements_due": [],
    "capabilities": {}
  },
  "event_object_changes": {},
  "event_created_at": "2025-01-15T10:30:00.000Z"
}

A new customer record was created. KYC has not yet started.

{
  "api_version": "v0",
  "event_id": "wh_c1a2b3c4d5e6f709",
  "event_sequence": 2,
  "event_developer_id": "dev_1a2b3c4d5e6f7081",
  "event_category": "customer",
  "event_type": "customer.updated.status_transitioned",
  "event_object_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
  "event_object_status": "incomplete",
  "event_object": {
    "id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "status": "incomplete",
    "type": "individual",
    "persona_inquiry_type": "standard",
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T10:35:00.000Z",
    "rejection_reasons": [],
    "has_accepted_terms_of_service": true,
    "endorsements": [],
    "future_requirements_due": [],
    "requirements_due": ["kyc_link"],
    "capabilities": {}
  },
  "event_object_changes": {
    "status": { "old": "not_started", "new": "incomplete" }
  },
  "event_created_at": "2025-01-15T10:35:00.000Z"
}

The customer accepted the Terms of Service and started KYC, but required fields or documents are still outstanding.

{
  "api_version": "v0",
  "event_id": "wh_c1a2b3c4d5e6f710",
  "event_sequence": 3,
  "event_developer_id": "dev_1a2b3c4d5e6f7081",
  "event_category": "customer",
  "event_type": "customer.updated.status_transitioned",
  "event_object_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
  "event_object_status": "awaiting_questionnaire",
  "event_object": {
    "id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "status": "awaiting_questionnaire",
    "type": "individual",
    "persona_inquiry_type": "standard",
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T10:40:00.000Z",
    "rejection_reasons": [],
    "has_accepted_terms_of_service": true,
    "endorsements": [],
    "future_requirements_due": [],
    "requirements_due": ["questionnaire"],
    "capabilities": {}
  },
  "event_object_changes": {
    "status": { "old": "incomplete", "new": "awaiting_questionnaire" }
  },
  "event_created_at": "2025-01-15T10:40:00.000Z"
}

Document and field collection is complete; the customer still needs to complete an additional compliance questionnaire before review can proceed.

{
  "api_version": "v0",
  "event_id": "wh_c1a2b3c4d5e6f711",
  "event_sequence": 4,
  "event_developer_id": "dev_1a2b3c4d5e6f7081",
  "event_category": "customer",
  "event_type": "customer.updated.status_transitioned",
  "event_object_id": "cust_3nV8VnRJxaQm3gavKPdSiF4",
  "event_object_status": "awaiting_ubo",
  "event_object": {
    "id": "cust_3nV8VnRJxaQm3gavKPdSiF4",
    "first_name": null,
    "last_name": null,
    "email": "finance@acmecorp.example.com",
    "status": "awaiting_ubo",
    "type": "business",
    "persona_inquiry_type": "standard",
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T10:45:00.000Z",
    "rejection_reasons": [],
    "has_accepted_terms_of_service": true,
    "endorsements": [],
    "future_requirements_due": [],
    "requirements_due": ["ultimate_beneficial_owners"],
    "capabilities": {}
  },
  "event_object_changes": {
    "status": { "old": "incomplete", "new": "awaiting_ubo" }
  },
  "event_created_at": "2025-01-15T10:45:00.000Z"
}

Business-type customer: still needs to submit ultimate beneficial owner information.

{
  "api_version": "v0",
  "event_id": "wh_c1a2b3c4d5e6f712",
  "event_sequence": 5,
  "event_developer_id": "dev_1a2b3c4d5e6f7081",
  "event_category": "customer",
  "event_type": "customer.updated.status_transitioned",
  "event_object_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
  "event_object_status": "under_review",
  "event_object": {
    "id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "status": "under_review",
    "type": "individual",
    "persona_inquiry_type": "standard",
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T11:00:00.000Z",
    "rejection_reasons": [],
    "has_accepted_terms_of_service": true,
    "endorsements": [],
    "future_requirements_due": [],
    "requirements_due": [],
    "capabilities": {}
  },
  "event_object_changes": {
    "status": { "old": "awaiting_questionnaire", "new": "under_review" }
  },
  "event_created_at": "2025-01-15T11:00:00.000Z"
}

All required information has been submitted and compliance is actively reviewing it.

{
  "api_version": "v0",
  "event_id": "wh_c1a2b3c4d5e6f713",
  "event_sequence": 6,
  "event_developer_id": "dev_1a2b3c4d5e6f7081",
  "event_category": "customer",
  "event_type": "customer.updated.status_transitioned",
  "event_object_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
  "event_object_status": "approved",
  "event_object": {
    "id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "status": "approved",
    "type": "individual",
    "persona_inquiry_type": "standard",
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-16T14:22:00.000Z",
    "rejection_reasons": [],
    "has_accepted_terms_of_service": true,
    "endorsements": [
      { "name": "transfers", "status": "approved", "requirements": [] },
      { "name": "liquidation_addresses", "status": "approved", "requirements": [] }
    ],
    "future_requirements_due": [],
    "requirements_due": [],
    "capabilities": {}
  },
  "event_object_changes": {
    "status": { "old": "under_review", "new": "approved" }
  },
  "event_created_at": "2025-01-16T14:22:00.000Z"
}

KYC passed and the customer is approved.

{
  "api_version": "v0",
  "event_id": "wh_c1a2b3c4d5e6f714",
  "event_sequence": 7,
  "event_developer_id": "dev_1a2b3c4d5e6f7081",
  "event_category": "customer",
  "event_type": "customer.updated.status_transitioned",
  "event_object_id": "cust_4nV8VnRJxaQm3gavKPdSiG5",
  "event_object_status": "rejected",
  "event_object": {
    "id": "cust_4nV8VnRJxaQm3gavKPdSiG5",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane@example.com",
    "status": "rejected",
    "type": "individual",
    "persona_inquiry_type": "standard",
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-16T15:00:00.000Z",
    "rejection_reasons": [
      { "developer_reason": "document_unverifiable", "bridge_reason": "unable_to_verify_identity_document" }
    ],
    "has_accepted_terms_of_service": true,
    "endorsements": [],
    "future_requirements_due": [],
    "requirements_due": [],
    "capabilities": {}
  },
  "event_object_changes": {
    "status": { "old": "under_review", "new": "rejected" }
  },
  "event_created_at": "2025-01-16T15:00:00.000Z"
}

Compliance review rejected the customer. rejection_reasons is populated.

{
  "api_version": "v0",
  "event_id": "wh_c1a2b3c4d5e6f715",
  "event_sequence": 8,
  "event_developer_id": "dev_1a2b3c4d5e6f7081",
  "event_category": "customer",
  "event_type": "customer.updated.status_transitioned",
  "event_object_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
  "event_object_status": "paused",
  "event_object": {
    "id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "status": "paused",
    "type": "individual",
    "persona_inquiry_type": "standard",
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-02-01T09:00:00.000Z",
    "rejection_reasons": [],
    "has_accepted_terms_of_service": true,
    "endorsements": [
      { "name": "transfers", "status": "paused", "requirements": [] }
    ],
    "future_requirements_due": [],
    "requirements_due": [],
    "capabilities": {}
  },
  "event_object_changes": {
    "status": { "old": "approved", "new": "paused" }
  },
  "event_created_at": "2025-02-01T09:00:00.000Z"
}

A previously approved customer has been paused (e.g. pending an RFI response or risk re-review); existing endorsements are suspended until the pause lifts.

{
  "api_version": "v0",
  "event_id": "wh_c1a2b3c4d5e6f716",
  "event_sequence": 9,
  "event_developer_id": "dev_1a2b3c4d5e6f7081",
  "event_category": "customer",
  "event_type": "customer.updated.status_transitioned",
  "event_object_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
  "event_object_status": "deposits_restricted",
  "event_object": {
    "id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "status": "deposits_restricted",
    "type": "individual",
    "persona_inquiry_type": "standard",
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-02-05T09:00:00.000Z",
    "rejection_reasons": [],
    "has_accepted_terms_of_service": true,
    "endorsements": [
      { "name": "transfers", "status": "approved", "requirements": [] }
    ],
    "future_requirements_due": [],
    "requirements_due": [],
    "capabilities": {}
  },
  "event_object_changes": {
    "status": { "old": "approved", "new": "deposits_restricted" }
  },
  "event_created_at": "2025-02-05T09:00:00.000Z"
}

New incoming deposits are restricted for this customer while other activity continues.

{
  "api_version": "v0",
  "event_id": "wh_c1a2b3c4d5e6f717",
  "event_sequence": 10,
  "event_developer_id": "dev_1a2b3c4d5e6f7081",
  "event_category": "customer",
  "event_type": "customer.updated.status_transitioned",
  "event_object_id": "cust_4nV8VnRJxaQm3gavKPdSiG5",
  "event_object_status": "offboarded",
  "event_object": {
    "id": "cust_4nV8VnRJxaQm3gavKPdSiG5",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane@example.com",
    "status": "offboarded",
    "type": "individual",
    "persona_inquiry_type": "standard",
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-03-01T09:00:00.000Z",
    "rejection_reasons": [],
    "has_accepted_terms_of_service": true,
    "endorsements": [],
    "future_requirements_due": [],
    "requirements_due": [],
    "capabilities": {}
  },
  "event_object_changes": {
    "status": { "old": "deposits_restricted", "new": "offboarded" }
  },
  "event_created_at": "2025-03-01T09:00:00.000Z"
}

The customer relationship has been terminated; this is a terminal status.

{
  "api_version": "v0",
  "event_id": "wh_c1a2b3c4d5e6f718",
  "event_sequence": 11,
  "event_developer_id": "dev_1a2b3c4d5e6f7081",
  "event_category": "customer",
  "event_type": "customer.updated",
  "event_object_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
  "event_object_status": "approved",
  "event_object": {
    "id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "status": "approved",
    "type": "individual",
    "persona_inquiry_type": "standard",
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-03-10T09:00:00.000Z",
    "rejection_reasons": [],
    "has_accepted_terms_of_service": true,
    "endorsements": [
      { "name": "transfers", "status": "approved", "requirements": [] }
    ],
    "future_requirements_due": [],
    "requirements_due": [],
    "capabilities": {}
  },
  "event_object_changes": {
    "email": { "old": "john@example.com", "new": "john.doe@example.com" }
  },
  "event_created_at": "2025-03-10T09:00:00.000Z"
}

A non-status field changed (here, email). status is unchanged, so this renders as a plain customer.updated rather than customer.updated.status_transitioned.

{
  "api_version": "v0",
  "event_id": "wh_c1a2b3c4d5e6f719",
  "event_sequence": 12,
  "event_developer_id": "dev_1a2b3c4d5e6f7081",
  "event_category": "customer",
  "event_type": "customer.deleted",
  "event_object_id": "cust_5nV8VnRJxaQm3gavKPdSiH6",
  "event_object_status": "not_started",
  "event_object": {
    "id": "cust_5nV8VnRJxaQm3gavKPdSiH6",
    "first_name": "Test",
    "last_name": "User",
    "email": "test@example.com",
    "status": "not_started",
    "type": "individual",
    "persona_inquiry_type": "standard",
    "created_at": "2025-03-15T10:30:00.000Z",
    "updated_at": "2025-03-15T10:30:00.000Z",
    "rejection_reasons": [],
    "has_accepted_terms_of_service": false,
    "endorsements": [],
    "future_requirements_due": [],
    "requirements_due": [],
    "capabilities": {}
  },
  "event_object_changes": {},
  "event_created_at": "2025-03-15T10:35:00.000Z"
}

The customer record was deleted (e.g. a test or duplicate record removed before KYC completed).

KYC Links

{
  "api_version": "v0",
  "event_id": "wh_k1l2m3n4o5p6q708",
  "event_sequence": 1,
  "event_developer_id": "dev_1a2b3c4d5e6f7081",
  "event_category": "kyc_link",
  "event_type": "kyc_link.created",
  "event_object_id": "kycl_abc123def456",
  "event_object_status": "not_started",
  "event_object": {
    "id": "kycl_abc123def456",
    "full_name": "John Doe",
    "email": "john@example.com",
    "type": "individual",
    "kyc_link": "https://verify.example.com/kyc?token=abc123",
    "tos_link": "https://bridge.xyz/tos/abc",
    "kyc_status": "not_started",
    "rejection_reasons": [],
    "tos_status": "pending",
    "created_at": "2025-01-15T10:30:00.000Z",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "persona_inquiry_type": "standard"
  },
  "event_object_changes": {},
  "event_created_at": "2025-01-15T10:30:00.000Z"
}

A KYC link was generated and sent to the customer. Neither KYC nor ToS acceptance has started.

{
  "api_version": "v0",
  "event_id": "wh_k1l2m3n4o5p6q709",
  "event_sequence": 2,
  "event_developer_id": "dev_1a2b3c4d5e6f7081",
  "event_category": "kyc_link",
  "event_type": "kyc_link.updated.status_transitioned",
  "event_object_id": "kycl_abc123def456",
  "event_object_status": "incomplete",
  "event_object": {
    "id": "kycl_abc123def456",
    "full_name": "John Doe",
    "email": "john@example.com",
    "type": "individual",
    "kyc_link": "https://verify.example.com/kyc?token=abc123",
    "tos_link": "https://bridge.xyz/tos/abc",
    "kyc_status": "incomplete",
    "rejection_reasons": [],
    "tos_status": "approved",
    "created_at": "2025-01-15T10:30:00.000Z",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "persona_inquiry_type": "standard"
  },
  "event_object_changes": {
    "kyc_status": { "old": "not_started", "new": "incomplete" },
    "tos_status": { "old": "pending", "new": "approved" }
  },
  "event_created_at": "2025-01-15T10:35:00.000Z"
}

The customer accepted the Terms of Service and began the KYC flow, but documents or fields are still outstanding.

{
  "api_version": "v0",
  "event_id": "wh_k1l2m3n4o5p6q710",
  "event_sequence": 3,
  "event_developer_id": "dev_1a2b3c4d5e6f7081",
  "event_category": "kyc_link",
  "event_type": "kyc_link.updated.status_transitioned",
  "event_object_id": "kycl_abc123def456",
  "event_object_status": "awaiting_questionnaire",
  "event_object": {
    "id": "kycl_abc123def456",
    "full_name": "John Doe",
    "email": "john@example.com",
    "type": "individual",
    "kyc_link": "https://verify.example.com/kyc?token=abc123",
    "tos_link": "https://bridge.xyz/tos/abc",
    "kyc_status": "awaiting_questionnaire",
    "rejection_reasons": [],
    "tos_status": "approved",
    "created_at": "2025-01-15T10:30:00.000Z",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "persona_inquiry_type": "standard"
  },
  "event_object_changes": {
    "kyc_status": { "old": "incomplete", "new": "awaiting_questionnaire" }
  },
  "event_created_at": "2025-01-15T10:40:00.000Z"
}

Documents are complete; an additional compliance questionnaire is still required.

{
  "api_version": "v0",
  "event_id": "wh_k1l2m3n4o5p6q711",
  "event_sequence": 4,
  "event_developer_id": "dev_1a2b3c4d5e6f7081",
  "event_category": "kyc_link",
  "event_type": "kyc_link.updated.status_transitioned",
  "event_object_id": "kycl_def456ghi789",
  "event_object_status": "awaiting_ubo",
  "event_object": {
    "id": "kycl_def456ghi789",
    "full_name": "Acme Corp",
    "email": "finance@acmecorp.example.com",
    "type": "business",
    "kyc_link": "https://verify.example.com/kyc?token=def456",
    "tos_link": "https://bridge.xyz/tos/def",
    "kyc_status": "awaiting_ubo",
    "rejection_reasons": [],
    "tos_status": "approved",
    "created_at": "2025-01-15T10:30:00.000Z",
    "customer_id": "cust_3nV8VnRJxaQm3gavKPdSiF4",
    "persona_inquiry_type": "standard"
  },
  "event_object_changes": {
    "kyc_status": { "old": "incomplete", "new": "awaiting_ubo" }
  },
  "event_created_at": "2025-01-15T10:45:00.000Z"
}

Business-type link: ultimate beneficial owner information is still required.

{
  "api_version": "v0",
  "event_id": "wh_k1l2m3n4o5p6q712",
  "event_sequence": 5,
  "event_developer_id": "dev_1a2b3c4d5e6f7081",
  "event_category": "kyc_link",
  "event_type": "kyc_link.updated.status_transitioned",
  "event_object_id": "kycl_abc123def456",
  "event_object_status": "under_review",
  "event_object": {
    "id": "kycl_abc123def456",
    "full_name": "John Doe",
    "email": "john@example.com",
    "type": "individual",
    "kyc_link": "https://verify.example.com/kyc?token=abc123",
    "tos_link": "https://bridge.xyz/tos/abc",
    "kyc_status": "under_review",
    "rejection_reasons": [],
    "tos_status": "approved",
    "created_at": "2025-01-15T10:30:00.000Z",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "persona_inquiry_type": "standard"
  },
  "event_object_changes": {
    "kyc_status": { "old": "awaiting_questionnaire", "new": "under_review" }
  },
  "event_created_at": "2025-01-15T11:00:00.000Z"
}

Submission is complete and compliance is actively reviewing it.

{
  "api_version": "v0",
  "event_id": "wh_k1l2m3n4o5p6q713",
  "event_sequence": 6,
  "event_developer_id": "dev_1a2b3c4d5e6f7081",
  "event_category": "kyc_link",
  "event_type": "kyc_link.updated.status_transitioned",
  "event_object_id": "kycl_abc123def456",
  "event_object_status": "approved",
  "event_object": {
    "id": "kycl_abc123def456",
    "full_name": "John Doe",
    "email": "john@example.com",
    "type": "individual",
    "kyc_link": "https://verify.example.com/kyc?token=abc123",
    "tos_link": "https://bridge.xyz/tos/abc",
    "kyc_status": "approved",
    "rejection_reasons": [],
    "tos_status": "approved",
    "created_at": "2025-01-15T10:30:00.000Z",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "persona_inquiry_type": "standard"
  },
  "event_object_changes": {
    "kyc_status": { "old": "under_review", "new": "approved" }
  },
  "event_created_at": "2025-01-16T14:22:00.000Z"
}

KYC passed and the underlying customer is approved.

{
  "api_version": "v0",
  "event_id": "wh_k1l2m3n4o5p6q714",
  "event_sequence": 7,
  "event_developer_id": "dev_1a2b3c4d5e6f7081",
  "event_category": "kyc_link",
  "event_type": "kyc_link.updated.status_transitioned",
  "event_object_id": "kycl_ghi789jkl012",
  "event_object_status": "rejected",
  "event_object": {
    "id": "kycl_ghi789jkl012",
    "full_name": "Jane Smith",
    "email": "jane@example.com",
    "type": "individual",
    "kyc_link": "https://verify.example.com/kyc?token=ghi789",
    "tos_link": "https://bridge.xyz/tos/ghi",
    "kyc_status": "rejected",
    "rejection_reasons": [
      { "developer_reason": "document_unverifiable", "bridge_reason": "unable_to_verify_identity_document" }
    ],
    "tos_status": "approved",
    "created_at": "2025-01-15T10:30:00.000Z",
    "customer_id": "cust_4nV8VnRJxaQm3gavKPdSiG5",
    "persona_inquiry_type": "standard"
  },
  "event_object_changes": {
    "kyc_status": { "old": "under_review", "new": "rejected" }
  },
  "event_created_at": "2025-01-16T15:00:00.000Z"
}

Compliance rejected the submission; rejection_reasons is populated.

{
  "api_version": "v0",
  "event_id": "wh_k1l2m3n4o5p6q715",
  "event_sequence": 8,
  "event_developer_id": "dev_1a2b3c4d5e6f7081",
  "event_category": "kyc_link",
  "event_type": "kyc_link.updated.status_transitioned",
  "event_object_id": "kycl_abc123def456",
  "event_object_status": "paused",
  "event_object": {
    "id": "kycl_abc123def456",
    "full_name": "John Doe",
    "email": "john@example.com",
    "type": "individual",
    "kyc_link": "https://verify.example.com/kyc?token=abc123",
    "tos_link": "https://bridge.xyz/tos/abc",
    "kyc_status": "paused",
    "rejection_reasons": [],
    "tos_status": "approved",
    "created_at": "2025-01-15T10:30:00.000Z",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "persona_inquiry_type": "standard"
  },
  "event_object_changes": {
    "kyc_status": { "old": "approved", "new": "paused" }
  },
  "event_created_at": "2025-02-01T09:00:00.000Z"
}

The underlying customer was paused after approval; the link mirrors that status.

{
  "api_version": "v0",
  "event_id": "wh_k1l2m3n4o5p6q716",
  "event_sequence": 9,
  "event_developer_id": "dev_1a2b3c4d5e6f7081",
  "event_category": "kyc_link",
  "event_type": "kyc_link.updated.status_transitioned",
  "event_object_id": "kycl_abc123def456",
  "event_object_status": "deposits_restricted",
  "event_object": {
    "id": "kycl_abc123def456",
    "full_name": "John Doe",
    "email": "john@example.com",
    "type": "individual",
    "kyc_link": "https://verify.example.com/kyc?token=abc123",
    "tos_link": "https://bridge.xyz/tos/abc",
    "kyc_status": "deposits_restricted",
    "rejection_reasons": [],
    "tos_status": "approved",
    "created_at": "2025-01-15T10:30:00.000Z",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "persona_inquiry_type": "standard"
  },
  "event_object_changes": {
    "kyc_status": { "old": "approved", "new": "deposits_restricted" }
  },
  "event_created_at": "2025-02-05T09:00:00.000Z"
}

Deposits are restricted for the underlying customer.

{
  "api_version": "v0",
  "event_id": "wh_k1l2m3n4o5p6q717",
  "event_sequence": 10,
  "event_developer_id": "dev_1a2b3c4d5e6f7081",
  "event_category": "kyc_link",
  "event_type": "kyc_link.updated.status_transitioned",
  "event_object_id": "kycl_ghi789jkl012",
  "event_object_status": "offboarded",
  "event_object": {
    "id": "kycl_ghi789jkl012",
    "full_name": "Jane Smith",
    "email": "jane@example.com",
    "type": "individual",
    "kyc_link": "https://verify.example.com/kyc?token=ghi789",
    "tos_link": "https://bridge.xyz/tos/ghi",
    "kyc_status": "offboarded",
    "rejection_reasons": [],
    "tos_status": "approved",
    "created_at": "2025-01-15T10:30:00.000Z",
    "customer_id": "cust_4nV8VnRJxaQm3gavKPdSiG5",
    "persona_inquiry_type": "standard"
  },
  "event_object_changes": {
    "kyc_status": { "old": "deposits_restricted", "new": "offboarded" }
  },
  "event_created_at": "2025-03-01T09:00:00.000Z"
}

The underlying customer relationship was terminated; terminal status.

{
  "api_version": "v0",
  "event_id": "wh_k1l2m3n4o5p6q718",
  "event_sequence": 11,
  "event_developer_id": "dev_1a2b3c4d5e6f7081",
  "event_category": "kyc_link",
  "event_type": "kyc_link.updated",
  "event_object_id": "kycl_abc123def456",
  "event_object_status": "approved",
  "event_object": {
    "id": "kycl_abc123def456",
    "full_name": "John Doe",
    "email": "john.doe@example.com",
    "type": "individual",
    "kyc_link": "https://verify.example.com/kyc?token=abc123",
    "tos_link": "https://bridge.xyz/tos/abc",
    "kyc_status": "approved",
    "rejection_reasons": [],
    "tos_status": "approved",
    "created_at": "2025-01-15T10:30:00.000Z",
    "customer_id": "cust_2nV8VnRJxaQm3gavKPdSiE3",
    "persona_inquiry_type": "standard"
  },
  "event_object_changes": {
    "email": { "old": "john@example.com", "new": "john.doe@example.com" }
  },
  "event_created_at": "2025-03-10T09:00:00.000Z"
}

A non-status field changed; kyc_status is unchanged so this renders as a plain kyc_link.updated rather than kyc_link.updated.status_transitioned.

Orchestration

Wallets

Issuance

Cards

Customers

Logistics

Additional information

Event structure

Supported Event Types

Event Object Schema

Event Object Schema Reference

Supported Mutation Types

Examples

Transfers

Liquidation Address Drains

Card Accounts

Card Transactions

Posted Card Account Transactions

Card Withdrawals

Virtual Account Activity

Static Memo Activity

External Accounts

Customers

KYC Links

​Supported Event Types

​Event Object Schema

​Event Object Schema Reference

​Supported Mutation Types

​Examples

​Transfers

​Liquidation Address Drains

​Card Accounts

​Card Transactions

​Posted Card Account Transactions

​Card Withdrawals

​Virtual Account Activity

​Static Memo Activity

​External Accounts

​Customers

​KYC Links

Supported Event Types

Event Object Schema

Event Object Schema Reference

Supported Mutation Types

Examples

Transfers

Liquidation Address Drains

Card Accounts

Card Transactions

Posted Card Account Transactions

Card Withdrawals

Virtual Account Activity

Static Memo Activity

External Accounts

Customers

KYC Links