Virtual Account Transaction
Learn when the virtual account transaction webhook is sent and what data it includes.
virtual_account_transaction_createdwhen the transaction is first recorded.virtual_account_transaction_updatedwhen it reaches a final status.
X-Meridian-Event-Type header tells you which one you received. Retry timing, signature verification, and endpoint configuration are covered in the webhooks overview.
Deposits by funding rail
Deposits can arrive over several rails, and the same fields carry different content depending on which one was used.| Rail | depositType | Currency values | Amount scale | originatorName / originatorAccount / originatorInstitution | fees |
|---|---|---|---|---|---|
| ACH | ACH | USD | 2 decimal places | Sender’s name, bank account number, and bank name | [] |
| Domestic wire | WIRE | USD | 2 decimal places | Sender’s name, bank account number, and bank name | One WIRE_PROCESSING_FEE |
| International wire | SWIFT | USD | 2 decimal places | Sender’s name, bank account number, and bank name | One SWIFT_PROCESSING_FEE |
| Stablecoin (on-chain) | ETHEREUM, BASE, or POLYGON | USDC_ETH, USDC_BASE, USDC_POLY, USDT_ETH, USDT_BASE, USDT_POLY | 6 decimal places | "", the sender’s wallet address, and "NOTPROVIDED" | [] |
Stablecoin sender fields
On stablecoin deposits, the sender fields hold wallet data, not bank data.| Field | Value on a stablecoin deposit |
|---|---|
originatorAccount | The sender’s wallet address, for example 0x5aAe…BeAed (42 characters) |
originatorName | The sender’s name when the sending VASP discloses it, otherwise "", an empty string |
originatorInstitution | The sending VASP’s name when it is known, otherwise "NOTPROVIDED" |
originatorName nor originatorInstitution is ever null on a stablecoin deposit, so a null check will not tell you the sender is unknown. Check for the empty string and the NOTPROVIDED sentinel.USDC_ETH name both the asset and its network. They are up to 9 characters and are not ISO 4217 codes, so a 3-character currency column will reject them.
Examples
Use the picker in the top-right corner of the JSON block below to switch between these examples:- ACH deposit (SUCCESS)
- Wire deposit with fee (SUCCESS)
- USDC deposit, sender not disclosed (SUCCESS)
- USDC deposit, sender disclosed (SUCCESS)
- Withdrawal (PENDING)
- Withdrawal (SUCCESS)
- ACH deposit (FAILED)
Authorizations
Meridian signs every webhook request it sends you.
Headers on every delivery:
- X-Meridian-Api-Key
- X-Meridian-Timestamp
- X-Meridian-Signature
X-Meridian-Signature is the hex-encoded HMAC-SHA256 of apiKey + timestamp + method + path + body, computed with your webhook secret. The webhook API key and secret are issued separately from your REST API credentials. Recompute it from the request you received and reject the delivery if it does not match. See Security in the webhooks overview.
Headers
The resource this event is about. Always virtual_account_transaction for this webhook.
"virtual_account_transaction"Which event fired. virtual_account_transaction_created when the transaction is first recorded, virtual_account_transaction_updated when it reaches a terminal status.
virtual_account_transaction_created, virtual_account_transaction_updated Your webhook API key. Meridian issues this separately from the API key you use to call the REST API, so do not expect the two to match. Use it to select the matching webhook secret when verifying the signature.
Time the request was signed, in milliseconds since the Unix epoch. Reject deliveries whose timestamp is too far from your clock to guard against replay.
Body
Webhook body. A single top-level key, virtualAccountTransaction, wraps the transaction. No event envelope, ID, or timestamp is added around it.
A virtual account transaction as delivered by the webhook. Every field is present on every event. Fields that do not apply to the transaction's direction or funding rail are sent as an explicit null, never omitted. Length limits are the current storage widths, useful for sizing your own columns, not contractual guarantees.
Show child attributes
Show child attributes
Response
Success