> ## Documentation Index > Fetch the complete documentation index at: https://apidocs.bridge.xyz/llms.txt > Use this file to discover all available pages before exploring further. # Virtual account events ## **What is a virtual account event?** Bridge generates a `VirtualAccountEvent` with a unique `id` whenever something happens on a Virtual Account — a deposit is received, a payment is processed, a refund is issued, or the account itself is updated. You can: * Fetch historical events using the [Virtual Account Activity API](/api-reference/virtual-accounts/virtual-account-activity). * Receive **real-time webhook notifications** when: * A new deposit is received. * The status of an event changes (e.g. funds delivered, refund issued). Each `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 the `type` field in the virtual account event object. | Type | Description | | :------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `funds_received` | Bridge received and matched a deposit to this Virtual Account. | | `payment_submitted` | Bridge submitted the crypto payment.

**Important:** the transaction hash provided at this stage may be preliminary and is not guaranteed to be final. Please use the transaction hash returned in the `payment_processed` state as the finalized transaction hash. | | `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. | | `refund_in_flight` | A refund has been initiated and is in progress. | | `refund_failed` | The refund attempt failed. This usually occurs for fiat deposits -- means the sending bank account Bridge is refunding to is closed, deactivated, or suspended. Before escalating to Bridge, please have your customer contact their sending bank to confirm the account's status. Bridge can only refund fiat deposits to the original sending account, so we'll need that account to be reachable before we can retry. | | `account_update` | Virtual Account was updated (e.g. new destination address). | | `deactivation` | Virtual Account was deactivated. | | `activation` | Virtual Account was reactivated after being deactivated. | | `microdeposit` | Microdeposit verification detected. Funds are never onramped. | **Deposit ID**\ \ 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** 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` - The payment rail on which the deposit was received: `ach_push`, `wire`, `sepa`, `faster_payments`, `spei`, or `pix`. Different information is available for each payment rail type. **ACH deposits** (`ach_push`) include these fields: * `description` - Sender-related information set by the sending bank according to NACHA ACH file specifications * `sender_bank_routing_number` - The routing number of the entity that initiated this ACH transaction * `sender_name` - The name of the business or individual who initiated the ACH * `trace_number` - A unique 15-digit number for tracking and reconciling transactions **Wire deposits** include these fields: * `bank_routing_number` - The routing number of the bank which sent this wire * `bank_name` - The name of the bank which sent this wire * `bank_beneficiary_name` - The beneficiary name of this wire * `bank_beneficiary_address` - The beneficiary address of this wire * `originator_name` - The originator name of this wire * `originator_address` - The originator address of this wire * `imad` - A unique FedWire payment identifier for investigation and tracking * `wire_message` - The memo for this wire **SEPA deposits** include these fields: * `reference` - Payment reference message for reconciliation * `iban` - The International Bank Account Number of the sender * `iban_last_4` - Last 4 digits of the sender's IBAN * `bic` - The Bank Identifier Code of the sender's bank * `sender_name` - The name of the individual or business who initiated the payment * `recipient_name` - The name of the payment recipient * `uetr` - Unique End-to-End Transaction Reference for tracking * `payment_scheme` - The specific payment scheme used (e.g., `sepa_credit`, `sepa_instant`) **Faster Payments deposits** include these fields: * `reference` - Payment reference message for reconciliation * `account_number` - The UK bank account number of the sender * `sort_code` - The six-digit sort code of the sender's bank * `last_4` - Last 4 digits of the sender's account number * `sender_name` - The name of the individual or business who initiated the payment * `recipient_name` - The name of the payment recipient * `uetr` - Unique End-to-End Transaction Reference for tracking **SPEI deposits** include these fields: * `description` - Transaction description from the sender * `reference` - Payment reference for reconciliation * `clabe` - The sender's CLABE (Mexican bank account identifier) * `tracking_number` - Unique identifier for tracking the transaction (*clave de rastreo*) * `sender_name` - The name of the sender **Pix deposits** include these fields: * `description` - Transaction description from the sender * `reference` - Payment reference for reconciliation * `tracking_number` - Unique identifier for tracking the transaction * `sender_name` - The name of the sender **Example: ACH Deposit** ```json theme={null} { "id": "va_event_457", "customer_id": "cust_alice", "virtual_account_id": "va_123", "type": "funds_received", "amount": "120.0", "currency": "usd", "developer_fee_amount": "1.25", "exchange_fee_amount": "2.2", "subtotal_amount": "120.0", "gas_fee": "0.0", "created_at": "2020-01-01T00:00:00.000Z", "deposit_id": "deposit_123", "source": { "payment_rail": "ach_push", "description": "ACH description", "sender_name": "The name of the business or individual who sent the ACH", "sender_bank_routing_number": "The routing number of the entity who sent this ACH transaction", "trace_number": "111222333444555" } } ``` **Example: Faster Payments Deposit** ```json theme={null} { "id": "va_event_789", "customer_id": "cust_bob", "virtual_account_id": "va_456", "type": "funds_received", "amount": "500.0", "currency": "gbp", "developer_fee_amount": "5.0", "exchange_fee_amount": "10.0", "subtotal_amount": "500.0", "gas_fee": "0.0", "created_at": "2025-12-15T10:30:00.000Z", "deposit_id": "deposit_fps_456", "source": { "payment_rail": "faster_payments", "reference": "Invoice 12345", "account_number": "12345678", "sort_code": "123456", "last_4": "5678", "sender_name": "John Smith", "recipient_name": "Bridge UK Ltd", "uetr": "97ed4827-7b6f-4491-a06f-b548d5a7512d" } } ``` **Example: SEPA Deposit** ```json theme={null} { "id": "va_event_890", "customer_id": "cust_charlie", "virtual_account_id": "va_789", "type": "funds_received", "amount": "750.0", "currency": "eur", "developer_fee_amount": "7.5", "exchange_fee_amount": "15.0", "subtotal_amount": "750.0", "gas_fee": "0.0", "created_at": "2025-12-16T14:20:00.000Z", "deposit_id": "deposit_sepa_789", "source": { "payment_rail": "sepa", "reference": "Order REF123456", "iban": "DE89370400440532013000", "iban_last_4": "3000", "bic": "COBADEFFXXX", "sender_name": "Maria Schmidt", "recipient_name": "Bridge EU", "uetr": "a7ed4827-7b6f-4491-a06f-b548d5a7513e", "payment_scheme": "sepa_credit" } } ``` **Example: Wire Deposit** ```json theme={null} { "id": "va_event_901", "customer_id": "cust_diana", "virtual_account_id": "va_101", "type": "funds_received", "amount": "2500.0", "currency": "usd", "developer_fee_amount": "25.0", "exchange_fee_amount": "50.0", "subtotal_amount": "2500.0", "gas_fee": "0.0", "created_at": "2025-12-17T09:15:00.000Z", "deposit_id": "deposit_wire_101", "source": { "payment_rail": "wire", "wire_message": "Payment for services", "bank_routing_number": "026009593", "bank_name": "Bank of America", "bank_beneficiary_name": "Bridge Inc", "bank_beneficiary_address": "789 Corporate Blvd, Suite 100, San Francisco, CA 94105", "originator_name": "Acme Corporation", "originator_address": "123 Main St, New York, NY 10001", "imad": "20251217BOFAUS3NXXX1234567890" } } ``` 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. ```json theme={null} { "id": "va_event_456", "customer_id": "cust_alice", "virtual_account_id": "va_123", "type": "payment_submitted", "amount": "116.66", "currency": "usd", "developer_fee_amount": "1.25", "exchange_fee_amount": "2.2", "subtotal_amount": "120.0", "gas_fee": "0.0", "created_at": "2020-01-01T00:00:00.000Z", "deposit_id": "deposit_123", "source": { "payment_rail": "ach_push", "description": "ACH description", "sender_name": "The name of the business or individual who sent the ACH", "sender_bank_routing_number": "The routing number of the entity who sent this ACH transaction", "trace_number": "111222333444555" }, "receipt": { "initial_amount": "120.0", "developer_fee": "1.25", "exchange_fee": "2.2", "subtotal_amount": "116.55", "url": "https://dashboard.bridge.xyz/transaction/dac30205-854f-4d8e-af41-d71bc1a48f13/receipt/eaf7a53b-d223-48e5-8089-23aa59862717", "gas_fee": "0.0", "final_amount": "116.55", } } ``` 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. The`destination_tx_hash`will 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. ```json theme={null} { "id": "va_event_456", "customer_id": "cust_alice", "virtual_account_id": "va_123", "type": "payment_processed", "amount": "116.55", "currency": "usd", "developer_fee_amount": "1.25", "exchange_fee_amount": "2.2", "subtotal_amount": "120.0", "gas_fee": "0.0", "created_at": "2020-01-01T00:00:00.000Z", "destination_tx_hash": "0xdeadbeef", "deposit_id": "deposit_123", "source": { "payment_rail": "ach_push", "description": "ACH description", "sender_name": "The name of the business or individual who sent the ACH", "sender_bank_routing_number": "The routing number of the entity who sent this ACH transaction", "trace_number": "111222333444555" }, "receipt": { "initial_amount": "120.0", "developer_fee": "1.25", "exchange_fee": "2.2", "subtotal_amount": "116.55", "url": "https://dashboard.bridge.xyz/transaction/dac30205-854f-4d8e-af41-d71bc1a48f13/receipt/eaf7a53b-d223-48e5-8089-23aa59862717", "gas_fee": "0.0", "final_amount": "116.55", "destination_tx_hash": "0xdeadbeef" } } ``` 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. ```json theme={null} { "id": "va_event_400f", "type": "funds_scheduled", "currency": "usd", "created_at": "2024-09-06T03:23:09.597Z", "customer_id": "cust_alice", "virtual_account_id": "va_123", "amount": "482.5", "source": { "payment_rail": "ach_push", "description": "ACH description", "sender_name": "The name of the business or individual who sent the ACH", "sender_bank_routing_number": "The routing number of the entity who sent this ACH transaction", "trace_number": "111222333444555", "estimated_arrival_date": "2024-09-06" } } ``` This event happens when a transaction enters the manual review queue. Bridge may reach out to obtain more information about the transaction before processing. ```json theme={null} { "id": "va_event_363", "customer_id": "cust_alice", "virtual_account_id": "va_123", "type": "in_review", "amount": "120.0", "currency": "usd", "developer_fee_amount": "1.25", "exchange_fee_amount": "2.2", "subtotal_amount": "120.0", "gas_fee": "0.0", "created_at": "2020-01-01T00:00:00.000Z", "deposit_id": "deposit_123", "source": { "payment_rail": "ach_push", "description": "ACH description", "sender_name": "The name of the business or individual who sent the ACH", "sender_bank_routing_number": "The routing number of the entity who sent this ACH transaction", "trace_number": "111222333444555" } } ``` There are three refund-related event types: `refund_in_flight`, `refunded`, and `refund_failed`. They follow the sequence described in [Event Type Transitions](#event-type-transitions). All refund events include a `refund` object with: * `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 **`refund_in_flight`** is emitted when Bridge initiates the return of funds to the sender. The return is in progress but not yet settled. ```json theme={null} { "id": "va_event_5dd678", "customer_id": "cust_alice", "virtual_account_id": "va_123", "deposit_id": "deposit_daec03", "type": "refund_in_flight", "amount": "98.76", "currency": "usd", "created_at": "2024-03-27T00:00:00.000Z", "source": { "description": "ACH description", "payment_rail": "ach_push", "sender_name": "The name of the business or individual who sent the ACH", "sender_bank_routing_number": "611161312", "trace_number": "111222333444555" }, "refund": { "code": "300", "reason": "Transaction Review", "refunded_at": "2024-03-27T00:00:00.000Z" } } ``` **`refunded`** is emitted when the return has fully settled and funds have been returned to the sender. This is a terminal event. ```json theme={null} { "id": "va_event_5dd679", "customer_id": "cust_alice", "virtual_account_id": "va_123", "deposit_id": "deposit_daec03", "type": "refunded", "amount": "98.76", "currency": "usd", "created_at": "2024-03-27T00:00:00.000Z", "source": { "description": "ACH description", "payment_rail": "ach_push", "sender_name": "The name of the business or individual who sent the ACH", "sender_bank_routing_number": "611161312", "trace_number": "111222333444555" }, "refund": { "code": "300", "reason": "Transaction Review", "refunded_at": "2024-03-27T00:00:00.000Z" } } ``` **`refund_failed`** is emitted when Bridge was unable to return the funds to the sender. This is a terminal event. ```json theme={null} { "id": "va_event_5dd681", "customer_id": "cust_alice", "virtual_account_id": "va_123", "deposit_id": "deposit_daec03", "type": "refund_failed", "amount": "98.76", "currency": "usd", "created_at": "2024-03-27T00:00:00.000Z", "source": { "description": "ACH description", "payment_rail": "ach_push", "sender_name": "The name of the business or individual who sent the ACH", "sender_bank_routing_number": "611161312", "trace_number": "111222333444555" }, "refund": { "code": "300", "reason": "Transaction Review", "refunded_at": "2024-03-27T00:00:00.000Z" } } ``` Note that not all refund events will include a `deposit_id`. This may be omitted in cases where the refund occurred before a deposit completed. For example: ```json theme={null} { "id": "va_event_5dd680", "customer_id": "cust_alice", "virtual_account_id": "va_123", "type": "refunded", "amount": "98.76", "currency": "usd", "created_at": "2024-03-27T00:00:00.000Z", "source": { "description": "wire description", "payment_rail": "wire", "originator_name": "The name of the business or individual who sent the wire", "originator_address": "The address of the sender", "bank_beneficiary_name": "The beneficiary name of this wire", "bank_beneficiary_address": "The beneficiary address of this wire", "bank_routing_number": "611161312", "imad": "20251217BOFAUS3NXXX1234567890" }, "refund": { "code": "610", "reason": "Wire Rejected: Unmatched", "refunded_at": "2024-03-27T00:00:00.000Z" } } ``` **Virtual Accounts support microdeposit and challenge deposit verification** to help your customers link external bank accounts.\ \ **This is currently only supported for ACH.** When a customer links their Virtual Account with another financial platform (e.g. a fintech app or payroll provider), they may be prompted to verify ownership through one of two methods: * **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. Bridge supports both of these methods by allowing microdebits and credits to pass through. Please note: * **Microdeposits are never onramped** – Any deposit under \$1 is treated as a verification attempt and will not trigger a payment or transfer. However, we do accumulate the balance of these microdeposits sent to your VA – once they exceed the minimum, we will onramp the combined ammount. * **Only Virtual Accounts support verification** – Static memo-based deposit flows (e.g. with shared memos) are not compatible with microdeposit verification We automatically generate a `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. ```json theme={null} { "id": "va_event_2641619d", "customer_id": "cust_alice", "virtual_account_id": "va_123", "type": "microdeposit", // indicates a microdeposit event "amount": "0.30", "currency": "usd", "created_at": "2024-01-03T19:09:46.676Z", "source": { "payment_rail": "ach_push", "description": "ACH description", "sender_name": "The name of the sending bank", "sender_bank_routing_number": "The routing number of the sending bank", "trace_number": "111222333444555" } }, { "id": "va_event_2c86b184", "customer_id": "cust_alice", "virtual_account_id": "va_123", "type": "microdeposit", "amount": "0.12", "currency": "usd", "created_at": "2024-01-03T19:09:46.676Z", "source": { "payment_rail": "ach_push", "description": "ACH description", "sender_name": "The name of the sending bank", "sender_bank_routing_number": "The routing number of the sending bank", "trace_number": "111222333444556" } }, { "id": "va_event_88294b57", "customer_id": "cust_alice", "virtual_account_id": "va_123", "type": "microdeposit", "amount": "-0.42", "currency": "usd", "created_at": "2024-01-03T19:13:19.281Z", "source": { "payment_rail": "ach_push", "description": "ACH description", "sender_name": "The name of the sending bank", "sender_bank_routing_number": "The routing number of the sending bank", "trace_number": "111222333444557" } } ``` If a Virtual Account is modified using the [Update a Virtual Account](/api-reference/virtual-accounts/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. ```json theme={null} { "id": "va_event_456", "customer_id": "cust_alice", "virtual_account_id": "va_123", "type": "account_update", "amount": "0.0", "currency": "usd", "created_at": "2020-01-01T00:00:00.000Z", "account_updates": { "destination_currency": ["usdc", "usdt"], } ``` ## Understanding Field Equivalents Across Payment Rails Different payment rails use different field names for similar concepts. This table shows how to map equivalent information across payment rails: | **Concept** | **ACH** | **SEPA/Faster Payments** | **SPEI** | **Wire** | | ----------------------- | ---------------------------- | --------------------------------------------------------------- | --------------------------- | --------------------- | | Transaction description | `description` | `reference` | `description` + `reference` | `wire_message` | | Sender identifier | `sender_bank_routing_number` | `iban` + `bic` (SEPA)
`account_number` + `sort_code` (FPS) | `clabe` | `bank_routing_number` | | Transaction trace | `trace_number` | `uetr` | `tracking_number` | `imad` | | Sender name | `sender_name` | `sender_name` | `sender_name` | `originator_name` | When building reconciliation logic, check `source.payment_rail` first, then access the appropriate fields for that rail. For example: * For ACH: Use `source.description` for the payment reference * For Faster Payments/SEPA: Use `source.reference` for the payment reference * For SPEI: Both `source.description` and `source.reference` may be populated * For Wire: Use `source.wire_message` for the payment reference ## Event Type Transitions Event types follow a defined lifecycle based on what happens to the deposit. The diagrams below show which event types can follow which. ### Normal onramp flow ```text theme={null} funds_scheduled ──► funds_received ──► payment_submitted ──► payment_processed (ACH only) ``` `funds_scheduled` is only emitted for ACH deposits, as a pre-settlement notification before funds actually arrive. `funds_received` is the first event for all other payment rails. If the deposit triggers a compliance review, `in_review` is inserted before `payment_submitted`: ```text theme={null} funds_received ──► in_review ──► payment_submitted ──► payment_processed ``` `payment_processed` is the terminal event for a successfully completed onramp. ### Refund flow A refund can be initiated at any point after `funds_received` — before processing starts, while in review, or after payment has been submitted. The refund path branches off from the normal flow: ```text theme={null} funds_received └──► refund_in_flight ──► refunded └──► refund_failed in_review └──► refund_in_flight ──► refunded └──► refund_failed payment_submitted └──► refund_in_flight ──► refunded └──► refund_failed ``` `refunded` and `refund_failed` are both terminal events — no further transaction events will be emitted for that deposit. ### Terminal events | Event type | Description | | :------------------ | :------------------------------------------------- | | `payment_processed` | Onramp completed successfully | | `refunded` | Funds returned to sender | | `refund_failed` | Return attempt failed; funds could not be returned | ### Independent events The following event types are not part of the deposit lifecycle and can occur at any time, independently of any transaction: | Event type | When it occurs | | :--------------- | :--------------------------------------------------------------------------- | | `account_update` | Virtual Account settings were changed (e.g. destination address or currency) | | `microdeposit` | A sub-\$1 verification deposit was received; funds are never onramped | | `activation` | Virtual Account was reactivated after being deactivated | | `deactivation` | Virtual Account was deactivated | ## Webhook Events Virtual account activity appears in `virtual_account.activity.*` webhook events. The webhook `event_object` uses the exact same structure as the virtual account event responses shown above. For webhook-specific details (envelope structure, signatures, delivery), see the [Webhook Structure](/platform/additional-information/webhooks/structure) documentation.