When an end user deposits funds to a merchant’s deposit address, NUSDpay sends a deposit event through a Webhook.

​
Crediting Logic

If either of the following conditions is met, the deposit can be considered credited:
  1. The event type is wallets.transaction.succeeded and status is Completed
  2. The on-chain confirmation count confirmed_num ≥ 10
Why are 10 blocks considered sufficient?Based on the Ethereum 2.0 Beacon Chain finality mechanism, the probability of a transaction being reverted after 10 blocks is extremely low. The official recommendation for full confirmation is 100 blocks (15–20 minutes), but 10 blocks already satisfy the safety requirements for the vast majority of business scenarios.

​
Payload Example

{
  "event_id": "48bf7cdc-7dd9-4d61-aa61-496003a4787c",
  "url": "https://apidev.nusd.me/webhooks/real",
  "created_timestamp": 1757407060503,
  "type": "wallets.transaction.created",
  "data": {
    "transaction_id": "157d3c84-294b-4ca1-8ca7-f0bbb3b98787",
    "wallet_id": "5c8e4ee0-e701-43b8-9724-7815d7c12643",
    "type": "Deposit",
    "status": "Confirming",
    "source": {
      "source_type": "DepositFromAddress",
      "addresses": ["0xf3f42f3d87ac8687b845146ec38aa9672d9669ab"]
    },
    "destination": {
      "destination_type": "DepositToAddress",
      "amount": "0.001",
      "address": "0x25246af7149a20b2d742b0796431df070eec7048",
      "wallet_id": "5c8e4ee0-e701-43b8-9724-7815d7c12643"
    },
    "chain_id": "TBSC_BNB",
    "token_id": "TBSC_BNB",
    "confirmed_num": 1,
    "confirming_threshold": 15,
    "transaction_hash": "0x77e1a72d410f279d589b185b4b74d4cc7e030cc67d42c7f0f0d3a96d84c08664",
    "block_info": {
      "block_number": 64752220,
      "block_timestamp": 1757407051000
    },
    "timeline": [{
      "status": "Confirming",
      "finished": false,
      "finished_timestamp": 1757407059000
    }]
  }
}

​
Field Reference

FieldTypeDescription
event_idstringUnique event identifier
typestringEvent type (wallets.transaction.created / updated / succeeded)
created_timestampnumberEvent creation timestamp (milliseconds)
data.transaction_idstringUnique transaction identifier
data.wallet_idstringMerchant wallet ID
data.typestringTransaction type (Deposit)
data.statusstringTransaction status (Confirming / Completed)
data.source.addressesarraySource addresses of the deposit (the end user’s addresses)
data.destination.amountstringDeposit amount
data.destination.addressstringDestination address of the deposit (the merchant’s deposit address)
data.chain_idstringChain identifier
data.token_idstringToken identifier
data.confirmed_numnumberCurrent on-chain confirmation count
data.confirming_thresholdnumberRequired minimum confirmation count
data.transaction_hashstringOn-chain transaction hash
data.block_infoobjectBlock info (block number, timestamp)
data.timelinearrayStatus change timeline

​
Handling Recommendations

A single deposit may trigger multiple Webhooks (created → updated → succeeded). Use transaction_id for idempotency to avoid double-crediting.
After receiving an event, first verify that data.wallet_id matches your project’s wallet. Events from other projects should be ignored.
In addition to Webhooks, we recommend periodically calling the Transaction Records endpoint as a reconciliation fallback in case Webhooks are lost.