Skip to main content

​
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.
  • 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.
TypeDescription
funds_receivedBridge received and matched a deposit to this Virtual Account.
payment_submittedBridge 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_processedPayment confirmed on-chain. Final state.
funds_scheduled(ACH only) Incoming funds are in transit with estimated arrival date.
in_reviewTransaction is under manual review.
refundedFunds could not be delivered and were refunded to the sender.
refund_in_flightA refund has been initiated and is in progress.
refund_failedA refund attempt failed.
account_updateVirtual Account was updated (e.g. new destination address).
deactivationVirtual Account was deactivated.
activationVirtual Account was reactivated after being deactivated.
microdepositMicrodeposit 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
{
  "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
{
  "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
{
  "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
{
  "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.
{
  "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. 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.
{
  "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.
{
    "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.
{
  "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.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.
{
  "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.
{
  "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.
{
  "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:
{
  "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.
{
  "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 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.
{
  "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:
ConceptACHSEPA/Faster PaymentsSPEIWire
Transaction descriptiondescriptionreferencedescription + referencewire_message
Sender identifiersender_bank_routing_numberiban + bic (SEPA)
account_number + sort_code (FPS)		clabebank_routing_number
Transaction tracetrace_numberuetrtracking_numberimad
Sender namesender_namesender_namesender_nameoriginator_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

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: 
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: 
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 typeDescription
payment_processedOnramp completed successfully
refundedFunds returned to sender
refund_failedReturn 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 typeWhen it occurs
account_updateVirtual Account settings were changed (e.g. destination address or currency)
microdepositA sub-$1 verification deposit was received; funds are never onramped
activationVirtual Account was reactivated after being deactivated
deactivationVirtual 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 documentation.