Fiat deposit lifecycle

A deposit moves through the provider asynchronously: fiat lands in the bank account, converts to crypto, then settles on-chain. Privy emits a webhook at each stage, keyed to a stable deposit_id.

Event	Fires when
`wallet.deposit_account.deposit_started`	Privy can confirm receipt of the deposit in the account, and has initiated the conversion.
`wallet.deposit_account.deposit_completed`	Conversion finished and the crypto settled on-chain in the wallet.
`wallet.deposit_account.deposit_failed`	Conversion failed and the fiat was refunded to the sender.

Webhooks can be tested at no cost in development environments. To enable webhooks in production, upgrade to the Enterprise plan in the Privy Dashboard.

Privy also emits the existing wallet.funds_deposited event when the crypto lands in the wallet.

Deposit started
Deposit completed
Deposit failed

Hide wallet.deposit_account.deposit_started attributes

'wallet.deposit_account.deposit_started'

required

Type of the webhook event.

string

required

ID of the deposit. Stable across every event for the same deposit.

string

required

ID of the deposit account that received the funds.

string

required

ID of the wallet the deposit is delivered to.

'fiat'

required

Type of the deposit.

'bridge'

required

Provider that orchestrated the deposit.

'production' | 'sandbox'

required

Provider environment the deposit account belongs to.

object

required

Details of the deposit.

Hide properties

string

required

Fiat amount received, as a decimal string.

'usd' | 'eur'

required

Currency of the fiat received.

object

required

The asset and chain the deposit is being converted into.

object

required

Details of the originator, containing sender_name and payment_rail.

string

required

When the deposit was received, as an ISO 8601 timestamp.

{
  "type": "wallet.deposit_account.deposit_started",
  "deposit_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "deposit_account_id": "da_xxxxx",
  "wallet_id": "dk3kud7kfo2jcnc5anoovdim",
  "deposit_type": "fiat",
  "provider": "bridge",
  "environment": "production",
  "data": {
    "amount": "1970.00",
    "currency": "usd",
    "destination": {
      "asset": "usdc",
      "chain": "tempo"
    },
    "source": {
      "sender_name": "John Doe",
      "payment_rail": "ach_push"
    },
    "created_at": "2026-08-03T14:30:00Z"
  }
}

The completed event carries the same fields as deposit_started, with the delivered crypto and the fees deducted during conversion.

Hide wallet.deposit_account.deposit_completed data attributes

string

required

Fiat amount that was deposited, as a decimal string.

'usd' | 'eur'

required

Currency of the fiat deposited.

object

required

Settlement details of the delivered crypto.

Hide properties

string

required

Asset delivered to the wallet.

string

required

Chain the asset was delivered on.

string

required

Crypto amount delivered, after conversion and fees.

string

required

Hash of the on-chain settlement transaction.

object

required

Details of the originator, containing sender_name and payment_rail.

object

required

Fees deducted during conversion, containing developer_fee, exchange_fee, and gas_fee.

string

required

When the crypto was delivered, as an ISO 8601 timestamp.

{
  "type": "wallet.deposit_account.deposit_completed",
  "deposit_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "deposit_account_id": "da_xxxxx",
  "wallet_id": "dk3kud7kfo2jcnc5anoovdim",
  "deposit_type": "fiat",
  "provider": "bridge",
  "environment": "production",
  "data": {
    "amount": "1970.00",
    "currency": "usd",
    "destination": {
      "asset": "usdc",
      "chain": "tempo",
      "amount": "1968.40",
      "transaction_hash": "0xabc123..."
    },
    "source": {
      "sender_name": "John Doe",
      "payment_rail": "ach_push"
    },
    "fees": {
      "developer_fee": "1.00",
      "exchange_fee": "0.50",
      "gas_fee": "0.10"
    },
    "created_at": "2026-08-03T14:32:00Z"
  }
}

Hide wallet.deposit_account.deposit_failed data attributes

string

required

Fiat amount that was refunded, as a decimal string.

'usd' | 'eur'

required

Currency of the refunded fiat.

object

required

The asset and chain the deposit would have been delivered as.

object

required

Details of the originator, containing sender_name and payment_rail.

object

required

Why the deposit failed, containing a machine-readable reason and a human-readable message.

string

required

When the refund settled, as an ISO 8601 timestamp.

string

required

When the failure was reported, as an ISO 8601 timestamp.

{
  "type": "wallet.deposit_account.deposit_failed",
  "deposit_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "deposit_account_id": "da_xxxxx",
  "wallet_id": "dk3kud7kfo2jcnc5anoovdim",
  "deposit_type": "fiat",
  "provider": "bridge",
  "environment": "production",
  "data": {
    "amount": "1970.00",
    "currency": "usd",
    "destination": {
      "asset": "usdc",
      "chain": "tempo"
    },
    "source": {
      "sender_name": "John Doe",
      "payment_rail": "ach_push"
    },
    "error": {
      "reason": "conversion_failed",
      "message": "Unable to convert funds — refund initiated"
    },
    "failed_at": "2026-08-03T14:35:00Z",
    "created_at": "2026-08-03T14:35:00Z"
  }
}

Funding

Deposits

Payouts

Deposit lifecycle

Next steps

Handling webhook events

Create a deposit account

​Next steps

Handling webhook events

Create a deposit account

Next steps