Deposit lifecycle

Follow a fiat deposit from bank receipt to on-chain settlement with webhooks

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 provider_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.

Every deposit event shares the same envelope, with the stage-specific details under data:

Hide shared attributes

type · string · required

Type of the webhook event.

provider_deposit_id · string

The deposit’s ID in the provider’s system, not a Privy ID. Stable across every event for the same deposit. Omitted on deposit_failed when the provider never assigned one.

deposit_account_id · string · required

ID of the deposit account that received the funds.

wallet_id · string · required

ID of the wallet the deposit is delivered to.

deposit_type · 'fiat' · required

Type of the deposit.

provider · 'bridge' · required

Provider that orchestrated the deposit.

environment · 'production' | 'sandbox' · required

Provider environment the deposit account belongs to.

Deposit started

Hide data attributes

data.source · object · required

The fiat that was received.

Hide properties

data.source.amount · string · required

Fiat amount deposited, as a decimal string.

data.source.currency · 'usd' | 'eur' · required

Currency of the fiat deposited.

data.source.payment_rail · string

Rail the deposit arrived over, such as ach_push, wire, sepa, fednow, or faster_payments.

data.source.sender_name · string

Name of the originator, when the rail provides it.

data.destination · object · required

The asset and chain the deposit is being converted into.

data.created_at · string · required

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

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

Deposit completed

The completed event carries the same source as deposit_started, and its destination adds the delivered crypto amount and the settlement transaction.

Hide data attributes

data.source · object · required

The fiat that was deposited, containing amount, currency, and optionally payment_rail and sender_name.

data.destination · object · required

Settlement details of the delivered crypto.

Hide properties

data.destination.asset · string · required

Asset delivered to the wallet.

data.destination.chain · string · required

Chain the asset was delivered on.

data.destination.amount · string · required

Crypto amount delivered, after conversion and fees.

data.destination.transaction_hash · string · required

Hash of the on-chain settlement transaction.

data.created_at · string · required

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

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

Deposit failed

Hide data attributes

data.source · object · required

The fiat that was refunded, containing amount, currency, and optionally payment_rail and sender_name.

data.destination · object · required

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

data.reason_code · string · required

Machine-readable failure code from the provider.

data.reason · string · required

Human-readable explanation of the failure.

data.refunded_at · string · required

When the refund settled, as an ISO 8601 timestamp.

data.created_at · string · required

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

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

Next steps

Handling webhook events

Configure an endpoint to receive Privy webhook events

Create a deposit account

Provision bank details for a wallet