Receive deposits

Know when money lands on a v2 account: the deposit webhooks for fiat-only and wallet-backed accounts, and how to credit once.

API version: v2.

When a payer sends money to an active account's bank details, Gravv books the deposit and sends webhooks of category transfer. Which webhooks you get depends on whether the account is fiat-only or wallet-backed.

A money example. Ada's client pays 1,200.00 USD by ACH into her wallet-backed account.

The bank turns it into USDC and sends it to the account's wallet on polygon. Gravv sends inflow.onchain.completed for the wallet.
Gravv books the full deposit and sends transfer.inflow.deposit_settled. Gravv bills any deposit fee on your plan for that rail to your business separately.
Both events describe one deposit. You credit Ada once, and GET /v2/accounts/{id} shows the new balance.

Webhooks by account

Account	Events
Fiat-only (USD at a US bank, EUR or GBP with one IBAN, NGN, Kenya-held)	`transfer.inflow.completed`
Wallet-backed	`transfer.inflow.deposit_settled` (`status` `settled`, `tokenized` `true`), and `inflow.onchain.completed` from the wallet side
Held for a decision on the Dashboard	`transfer.inflow.awaiting_approval` first
The credit failed or was reversed	`transfer.inflow.payout_failed` or `transfer.inflow.compensated`

event_group_id is the deposit's transaction_id. A wallet-backed deposit's settlement_event_group_id is the event_group_id of its on-chain event. Use it to link the two events and credit the customer once.

{
  "event_id": "7d1e3f5a-9b2c-4d6e-8f0a-1b3c5d7e9f20",
  "event_type": "transfer.inflow.completed",
  "event_category": "transfer",
  "event_group_id": "4a6c8e0b-2d4f-4b6a-8c0e-3f5b7d9a1c2e",
  "tenant_id": "5d0c9b8a-7f6e-4d5c-8b4a-3f2e1d0c9b8a",
  "timestamp": "2026-10-14T10:00:00Z",
  "event_data": {
    "transaction_id": "4a6c8e0b-2d4f-4b6a-8c0e-3f5b7d9a1c2e",
    "status": "completed",
    "amount": "3200.00",
    "currency": "USD",
    "account_id": "9c1e3a5b-7d9f-4b2e-8a4c-6e8a0c2e4b6d",
    "sender_name": "Front Range Catering",
    "sender_account_number": "000123456789",
    "sender_bank": "Example Community Bank",
    "narration": "Invoice 2041"
  }
}

amount is a decimal string in the account's currency. Gravv does not take its deposit fee out of it.

Rules

Deduplicate on the body's event_id. Two services send events for a wallet-backed deposit, and retries repeat events.
A wallet-backed account books only USDC on its blockchain_network. Gravv does not credit another token, or a token on another network, sent to wallet_address. If this happens, contact support.
For a wallet-backed account, the bank deposit finishes only when the matching USDC reaches the wallet. If nothing arrives after the rail's normal time, give support the account id, amount and date.
Gravv never takes its deposit fee for a rail out of the deposit. Gravv takes the fee from your business's main account or puts it on your monthly invoice. The fee has its own fee_charge row. See See a deposit arrive. If the amount is lower than what the payer sent, the difference comes from the sending side, such as a bank's charges on the way.
Read balances as described on List and read accounts.

To produce these webhooks without a real transfer, see Test accounts in sandbox.