Virtual accounts
Virtual account events
What is a virtual account event?
Whenever a deposit is received, Bridge generates aVirtualAccountEvent with a unique id. You can:
- Fetch historical events using the Virtual Account Activity API.
- Receive real-time webhook notifications when:
- A new deposit is received.
- The status of an event changes (e.g. funds delivered, refund issued).
VirtualAccountEvent includes detailed information about the deposit, source, status, and destination.
Event Types
Below are the different types of virtual account events you may receive. You can identify the type of each event by checking thetype field in the virtual account event object.
| Type | Description |
|---|---|
funds_received | Bridge received funds via ACH or wire. |
payment_submitted | Bridge submitted the crypto payment. |
payment_processed | Payment confirmed on-chain. Final state. |
funds_scheduled | (ACH only) Incoming funds are in transit with estimated arrival date. |
in_review | Transaction is under manual review. |
refunded | Funds could not be delivered and were refunded to the sender. |
account_update | Virtual Account was updated (e.g. new destination address). |
deactivation | Virtual Account was deactivated. |
reactivation | Virtual Account was reactivated. |
microdeposit | Microdeposit verification detected. Funds are never onramped. |
Deposit ID
All transaction-triggered events include a
All transaction-triggered events include a
deposit_id field. This id is unique for each transaction that Bridge receives through this Virtual Account and can be used to link separate events to the same source transaction.Event Breakdown
Funds received
Funds received
Information about a fiat deposit received. The
funds_received event amount always matches the full amount that the customer sent before any fees are deducted. We also provide any source information we have about the sender of a deposit.payment_rail-ach_pushorwire. The payment rail on which the deposit was received. Different information is available for each of these payment rail types.- For ACH deposits, funding events have these details:
description- This field contains the sender-related information set by the sending bank according to the NACHA ACH file specifications;sender_routing_number- The routing number of the entity that initiated this ACH transactionsender_name- The name of the business or individual who initiated the ACH as provided through the ACH systemtrace_number- The unique, a 15-digit number associated with each ACH transaction that is used for tracking and reconciling transactions
- For wire deposits, funding events have these details:
bank_routing_number- The routing number of the bank which sent this wirebank_name- The name of the bank which sent this wirebank_beneficiary_name- The name the sender used for the beneficiary name of the wireoriginator_name- The name of the senderoriginator_address- The address of the senderimad- A unique number given to each FedWire payment when using the Federal Reserve Bank Service which can be used to investigate and track wire transfers.
Payment submitted
Payment submitted
Information about any funds sent on chain using the deposit instructions. This event is created when the funds are sent on chain. The
payment_submitted event amount is the funds sent to the destination after all fees are taken out and includes a breakdown of the amount of each fee. Some information such as destination_tx_hash may not be available immediately after the event is created but will be populated later when the transaction is confirmed on chain.For convenience, the source deposit information is included in this event as well if available.Payment processed
Payment processed
Information about any funds sent on chain using the deposit instructions. This event is created when the funds are confirmed on chain. The
payment_processed event amount is the funds sent to the destination after all fees are taken out and includes a breakdown of the amount of each fee. Thedestination_tx_hashwill always be populated for these events. This is final event in the onramp payment lifecycle and the best event to determine when a payment is fully complete.For convenience, the source deposit information is included in this event as well if available.Funds scheduled
Funds scheduled
The events provides a notification that incoming funds are processing through the ACH system and an estimated arrival date for the credit. These events only occur for funds sent through ACH.
In review
In review
This event happens when a transaction enters the manual review queue. Bridge may reach out to obtain more information about the transaction before processing.
Refund events
Refund events
Information about funds this Virtual Account received which were refunded back to the sender. Details about the refund are included in the “refund” section of the event which includes:Note that not all refund events will include a
- Reason: a brief, human-readable explanation of why this transaction was refunded
- Code: an alphanumeric code representing the reason inside Bridge’s system
- Refunded At: when the refund was initiated
deposit_id. This may be omitted in cases where the refund occurred before a deposit completed. For example:Bank verification
Bank verification
Virtual Accounts support microdeposit and challenge deposit verification to help your customers link external bank accounts.
- Microdeposit Verification – A small amount (typically less than $1) is deposited and withdrawn to confirm the account is active.
- Challenge deposit verification – One or more microdeposits are made, and the customer must input the exact deposit amounts (e.g. $0.56 and $0.84) to pass verification.
- Microdeposits are never onramped – Any deposit under $1 is treated as a verification attempt and will not trigger a payment or transfer.
- Only Virtual Accounts support verification – Static memo-based deposit flows (e.g. with shared memos) are not compatible with microdeposit verification
microdeposit event for each verification attempt. This event includes the amount, source bank details, and timestamp—so you can display them to the customer for verification if needed.Credit and debit entries (positive and negative amounts) may both appear during the verification process. However, some providers may only send a credit—behavior varies by the verifying institution.
Account update
Account update
If a Virtual Account is modified using the Update a Virtual Account endpoint, its history will include an
account_update event to track what changed. The account_updates field in this event will contain a map of fields with their previous and updated values.