Wallet Deposit Events

Fired when funds arrive in one of your wallets.

Event	Trigger
`wallet.deposit`	An on-chain crypto deposit arrived at one of your wallet addresses
`wallet.deposit.internal`	An internal transfer from another 100Pay wallet was received

The two events share the same shape — transferType distinguishes them ("onchain" vs "internal").

Payload


interface WalletDepositWebhook {
  eventType: "wallet.deposit" | "wallet.deposit.internal";
  transferType: "onchain" | "internal";
  _id: string;                 // ledger transaction ID
  transactionHash: string;     // on-chain tx hash, or internal transfer hash
  transactionSignature: string;
  status: "successful" | "pending" | "failed";
  type: "credit";
  amount: string;
  symbol: string;              // e.g. "USDT", "NGN"
  network?: string;            // e.g. "bsc", "ethereum" — on-chain deposits
  from: string;                // sender address or wallet code
  to: string;                  // your receiving address or wallet code
  note?: string;               // sender note (internal transfers)
  category: string;
  timestamp: string;
  accountId: string;
  appId: string;
  userId: string;
  metadata?: Record<string, unknown>; // wallet metadata you set at creation
}

Example — `wallet.deposit` (on-chain)


{
  "eventType": "wallet.deposit",
  "transferType": "onchain",
  "_id": "665f1c2e8b6a4a0012a4d960",
  "transactionHash": "0x9f8e7d6c5b4a39281706f5e4d3c2b1a0ffeeddccbbaa99887766554433221100",
  "transactionSignature": "0x9f8e...1100-credit-0xSenderAddr-0xYourAddr",
  "status": "successful",
  "type": "credit",
  "amount": "50.00",
  "symbol": "USDT",
  "network": "bsc",
  "from": "0x1234abcd5678ef901234abcd5678ef901234abcd",
  "to": "0xabcd1234ef567890abcd1234ef567890abcd1234",
  "category": "uncategorized",
  "timestamp": "2026-03-12T13:30:00.000Z",
  "accountId": "665f0aa18b6a4a0012a4d100",
  "appId": "62ee5dbfb029b7002d5b7453",
  "userId": "628b228b19ac52002c588525",
  "metadata": { "orderRef": "order_42" }
}

metadata echoes back the metadata you attached when creating the wallet — use it to map deposits to users or orders in your system without a database lookup on the address.

Example — `wallet.deposit.internal`


{
  "eventType": "wallet.deposit.internal",
  "transferType": "internal",
  "_id": "665f1c2e8b6a4a0012a4d970",
  "transactionHash": "internal-transfer-665f1c2e8b6a4a0012a4d96f",
  "transactionSignature": "internal-transfer-665f1c2e8b6a4a0012a4d96f-credit-625988-916698",
  "status": "successful",
  "type": "credit",
  "amount": "500",
  "symbol": "NGN",
  "from": "916698",
  "to": "625988",
  "note": "Hello there!",
  "category": "uncategorized",
  "timestamp": "2026-03-12T13:32:35.200Z",
  "accountId": "665f0aa18b6a4a0012a4d100",
  "appId": "62ee5dbfb029b7002d5b7453",
  "userId": "628b228b19ac52002c588525"
}

Handling


async function handleWalletDeposit(event: WalletDepositWebhook) {
  if (event.status !== "successful") return;
 
  // Map to your user via wallet metadata or the receiving address
  const user = await findUserByWallet(event.to, event.metadata);
 
  await creditUser(user.id, {
    amount: event.amount,
    currency: event.symbol,
    ref: event.transactionHash, // idempotency key at the resource level
    onChain: event.transferType === "onchain",
  });
}

The sender of an internal transfer receives a separate transaction.withdrawal event — wallet.deposit.internal is delivered to the recipient’s app.