Virtual Account Activity

curl --request GET \
  --url https://api.bridge.xyz/v0/customers/{customerID}/virtual_accounts/{virtualAccountID}/history \
  --header 'Api-Key: <api-key>'

{
  "count": 3,
  "data": [
    {
      "id": "va_event_456",
      "customer_id": "cust_alice",
      "virtual_account_id": "va_123",
      "type": "payment_submitted",
      "amount": "120.0",
      "currency": "usd",
      "developer_fee_amount": "1.25",
      "exchange_fee_amount": "2.2",
      "subtotal_amount": "120.0",
      "gas_fee": "0.0",
      "deposit_id": "deposit_123",
      "created_at": "2024-01-01T00:00:00.000Z",
      "destination_tx_hash": "0xdeadbeef",
      "source": {
        "payment_rail": "ach_push",
        "description": "ACH description",
        "sender_name": "The name of the business or individual who initiated the ACH",
        "sender_bank_routing_number": "The routing number of the entity that initiated this ACH transaction",
        "trace_number": "The unique, a 15-digit number associated with each ACH transaction that is used for tracking and reconciling transactions"
      }
    },
    {
      "id": "va_event_123",
      "customer_id": "cust_alice",
      "virtual_account_id": "va_123",
      "type": "funds_received",
      "amount": "123.45",
      "currency": "usd",
      "developer_fee_amount": "0.0",
      "exchange_fee_amount": "0.0",
      "subtotal_amount": "123.45",
      "gas_fee": "0.0",
      "deposit_id": "deposit_123",
      "created_at": "2024-01-01T00:00:00.000Z",
      "source": {
        "payment_rail": "ach_push",
        "description": "ACH description",
        "sender_name": "The name of the business or individual who initiated the ACH",
        "sender_bank_routing_number": "The routing number of the entity that initiated this ACH transaction",
        "trace_number": "The unique, a 15-digit number associated with each ACH transaction that is used for tracking and reconciling transactions"
      }
    },
    {
      "id": "va_event_789",
      "customer_id": "cust_alice",
      "virtual_account_id": "va_456",
      "type": "payment_processed",
      "amount": "123.45",
      "currency": "usdc",
      "developer_fee_amount": "0.0",
      "exchange_fee_amount": "0.0",
      "subtotal_amount": "123.45",
      "gas_fee": "0.0",
      "deposit_id": "deposit_789",
      "created_at": "2025-06-01T00:00:00.000Z",
      "source": {
        "payment_rail": "spei",
        "description": "Receiving CLABE | clave de rastreo | SPEI reference",
        "tracking_number": "The unique tracking number or clave de rastreo for this SPEI transaction",
        "sender_name": "The name of the business or individual who initiated the SPEI credit",
        "reference": "The reference or concepto de pago for this SPEI transaction"
      }
    }
  ]
}

GET

customers

{customerID}

virtual_accounts

{virtualAccountID}

history

Virtual Account Activity

curl --request GET \
  --url https://api.bridge.xyz/v0/customers/{customerID}/virtual_accounts/{virtualAccountID}/history \
  --header 'Api-Key: <api-key>'

{
  "count": 3,
  "data": [
    {
      "id": "va_event_456",
      "customer_id": "cust_alice",
      "virtual_account_id": "va_123",
      "type": "payment_submitted",
      "amount": "120.0",
      "currency": "usd",
      "developer_fee_amount": "1.25",
      "exchange_fee_amount": "2.2",
      "subtotal_amount": "120.0",
      "gas_fee": "0.0",
      "deposit_id": "deposit_123",
      "created_at": "2024-01-01T00:00:00.000Z",
      "destination_tx_hash": "0xdeadbeef",
      "source": {
        "payment_rail": "ach_push",
        "description": "ACH description",
        "sender_name": "The name of the business or individual who initiated the ACH",
        "sender_bank_routing_number": "The routing number of the entity that initiated this ACH transaction",
        "trace_number": "The unique, a 15-digit number associated with each ACH transaction that is used for tracking and reconciling transactions"
      }
    },
    {
      "id": "va_event_123",
      "customer_id": "cust_alice",
      "virtual_account_id": "va_123",
      "type": "funds_received",
      "amount": "123.45",
      "currency": "usd",
      "developer_fee_amount": "0.0",
      "exchange_fee_amount": "0.0",
      "subtotal_amount": "123.45",
      "gas_fee": "0.0",
      "deposit_id": "deposit_123",
      "created_at": "2024-01-01T00:00:00.000Z",
      "source": {
        "payment_rail": "ach_push",
        "description": "ACH description",
        "sender_name": "The name of the business or individual who initiated the ACH",
        "sender_bank_routing_number": "The routing number of the entity that initiated this ACH transaction",
        "trace_number": "The unique, a 15-digit number associated with each ACH transaction that is used for tracking and reconciling transactions"
      }
    },
    {
      "id": "va_event_789",
      "customer_id": "cust_alice",
      "virtual_account_id": "va_456",
      "type": "payment_processed",
      "amount": "123.45",
      "currency": "usdc",
      "developer_fee_amount": "0.0",
      "exchange_fee_amount": "0.0",
      "subtotal_amount": "123.45",
      "gas_fee": "0.0",
      "deposit_id": "deposit_789",
      "created_at": "2025-06-01T00:00:00.000Z",
      "source": {
        "payment_rail": "spei",
        "description": "Receiving CLABE | clave de rastreo | SPEI reference",
        "tracking_number": "The unique tracking number or clave de rastreo for this SPEI transaction",
        "sender_name": "The name of the business or individual who initiated the SPEI credit",
        "reference": "The reference or concepto de pago for this SPEI transaction"
      }
    }
  ]
}

Authorizations

Api-Key

string

header

required

Path Parameters

customerID

string

required

A UUID that uniquely identifies a resource

Required string length: 1 - 42

virtualAccountID

string

required

A UUID that uniquely identifies a resource

Required string length: 1 - 42

Query Parameters

deposit_id

string

The deposit id associated with the events. Cannot be passed if deposit_ids is also passed

deposit_ids

string[]

The deposit ids associated with the events. Pass a list of deposit ids like "deposit_ids[]=id1&deposit_ids[]=id2". Cannot be passed if deposit_id is also passed

tx_hash

string

The hash of the transaction

limit

integer

The number of items to return (default of 10, max of 100)

starting_after

string

This is an event id. If this is specified, the next page that starts with an event right AFTER the specified event id on the event timeline, which is always ordered from the newest to the oldest by creation time, will be returned. This also implies that events older than the specified event id will be returned (shouldn't be set if ending_before is set)

ending_before

string

This is an event id. If this is specified, the previous page that ends with an event right BEFORE the specified event id on the event timeline, which is always ordered from the newest to the oldest by creation time, will be returned. This also implies that events newer than the specified event id will be returned (shouldn't be set if starting_after is set)

event_type

enum<string>

Filter history by event type

Available options:

funds_received,

payment_submitted,

payment_processed,

in_review,

refund,

microdeposit,

account_update,

deactivation,

activation

Response

200 - application/json

List of Virtual Account events

count

integer

required

The number of events returned

data

object[]

required

Show child attributes

data.id

string

required

A UUID that uniquely identifies a resource

Required string length: 1 - 42

data.type

enum<string>

The type of activity

Available options:

funds_scheduled,

funds_received,

payment_submitted,

payment_processed,

in_review,

refund,

microdeposit,

account_update,

deactivation,

activation

data.customer_id

string

The id of the Bridge customer that this Virtual Account event belongs to

Required string length: 1 - 42

data.virtual_account_id

string

The id of the Virtual Account that this Virtual Account event belongs to

Required string length: 1 - 42

data.amount

string

Amount for that event, represented as a dollar denominated string. Examples include "100.25", "0.1", "1.234567" etc. For "incoming" events such as funds_received or under_review, this is the initial amount received. For "outgoing" events such as payment_submitted and payment_processed, this is the amount of funds sent to the destination. For non-transactional events such as account_update, this will be zero.

data.currency

enum<string>

Available options:

usdb,

usdc,

usdt,

dai,

usd,

pyusd

data.developer_fee_amount

string

Amount of the developer fee if any, represented as a dollar denominated string. This is the final amount taken out of what is ultimately received by your customer, not a percentage. Examples include "100.25", "0.1", "1.234567" etc.

data.exchange_fee_amount

string

Amount of the exchange fee if any, represented as a dollar denominated string. Examples include "100.25", "0.1", "1.234567" etc.

data.subtotal_amount

string

Amount of the subtotal, represented as a dollar denominated string. Examples include "100.25", "0.1", "1.234567" etc.

data.gas_fee

string

Amount of the gas fee if any, represented as a dollar denominated string. Examples include "100.25", "0.1", "1.234567" etc.

data.deposit_id

string

The id of the deposit related to this event. This id can be used to link multiple events to the same transaction. Omitted for some refund cases.

data.destination_tx_hash

string

The hash of the on-chain transfer to the destination address

data.destination_payment_rail

string

The destination payment rail where the funds are deposited to

data.source

object

Show child attributes

data.source.payment_rail

enum<string>

required

Available options:

ach_push,

pix,

sepa,

spei,

wire

data.source.description

string

(ACH and SPEI only) The description of the deposit that the customer sent

data.source.sender_name

string

(ACH, SEPA, and SPEI only) The name of the business or individual who initiated the transaction

data.source.sender_bank_routing_number

string

(ACH only) The routing number of the entity that initiated this ACH transaction

data.source.trace_number

string

(ACH only) The unique, a 15-digit number associated with each ACH transaction that is used for tracking and reconciling transactions

data.source.bank_routing_number

string

(Wire only) The routing number of the bank that sent the wire to the Virtual Account

data.source.bank_name

string

(Wire only) The name of the bank that sent the wire

data.source.bank_beneficiary_name

string

(Wire only) The beneficiary name of this wire

data.source.bank_beneficiary_address

string

(Wire only) The beneficiary address of this wire

data.source.originator_name

string

(Wire only) The originator name of this wire

data.source.originator_address

string

(Wire only) The originator address of this wire

data.source.wire_message

string

(Wire only) The memo for this wire

data.source.imad

string

(Wire only) The IMAD of a wire transfer, if available

Required string length: 1 - 40

data.source.bic

string

(SEPA only) The BIC of the bank that initiated this transaction

data.source.iban

string

(SEPA only) The full IBAN of the account that initiated this transaction

data.source.iban_last_4

string

(SEPA only) The last 4 digits of the IBAN of the account that initiated this transaction

data.source.clabe

string

(SPEI only) The CLABE (account number) of the account that initiated this transaction

data.source.reference

string

(SEPA and SPEI only) The SEPA/SPEI (concepto de pago) reference field set by the initiator of this transaction

Required string length: 6 - 140

data.source.tracking_number

string

(SPEI only) The clave de rastreo or tracking number of the SPEI transaction

data.source.payment_scheme

enum<string>

(SEPA only) The payment scheme used for this transaction, such as SEPA Credit Transfer or SEPA Instant

Available options:

reversed_payment,

sepa_credit,

sepa_instant

data.source.uetr

string

The UETR of this SEPA transaction, for tracing purposes.

Required string length: 36

data.created_at

string<date-time>

Time of creation of the event

data.receipt

object

Receipt information of a virtual account event. Available for drain and payment_processed events.

Show child attributes

data.receipt.initial_amount

string

required

The initial amount of the transfer, represented as a decimal string. Examples include "100.25", "0.1", "1.234567", "1.01" etc.

It's denominated in the transfer's fiat currency (see the top-level currency field for more info)

data.receipt.developer_fee

string

required

The fee, expressed as a decimal string, represents the amount you wish to reserve for your own account. This fee is the final amount deducted from what your customer ultimately receives, rather than a percentage.

It is denominated in the transfer's fiat currency (see the top-level currency field for more info).

data.receipt.exchange_fee

string

required

The fee, expressed as a decimal string, represents the amount Bridge charges for facilitating the transfer. This is the final amount to take out of what is ultimately received by your customer, not a percentage.

It's denominated in the transfer's fiat currency (see top-level currency field for more info).

data.receipt.subtotal_amount

string

required

The initial amount of the transfer less fixed fees (including the developer_fee and exchange_fee). Examples include "100.25", "0.1", "1.234567", "1.01" etc.

It's denominated in the transfer's fiat currency (see top-level currency field for more info).

data.receipt.remaining_prefunded_balance

string

For Prefunded Accounts, this value will represent the remaining account balance after the transfer.

data.receipt.gas_fee

string

The fee, expressed as a decimal string. It's deducted from the withdrawn amount to pay for gas. Only nonzero to crypto withdrawals that cost gas (e.g. USDT or DAI), and only known when the transaction is confirmed on-chain. Will be missing if not yet known.

It's denominated in the fiat currency to which the destination currency is pegged.

data.receipt.final_amount

string

The final amount of the transfer, expressed as a decimal string, equal to the subtotal_amount minus any gas fees. If the gas fee is not known, this field will be missing. Examples include "100.25", "0.1", "1.234567", "1.01" etc.

It's denominated in the destination currency if that is a fiat currency or the fiat currency to which the destination currency is pegged.

data.receipt.source_tx_hash

any

The hash of the on-chain deposit to the source address, where applicable

data.receipt.destination_tx_hash

any

The hash of the on-chain transfer to the destination address, where applicable

data.receipt.exchange_rate

any

The effective exchange rate can be calculated by dividing the converted amount by the amount available for conversion after deducting the developer fee. This rate includes a currency conversion spread and is subject to a rounding precision loss during the calculation. Currently it's populated for SEPA onramp/offramp transfers only.

data.receipt.url

string

The URL of a user-facing copy of the receipt.

Reactivate a Virtual Account List Virtual Accounts

⌘I

Endpoints

Authorizations

Path Parameters

Query Parameters

Response