Skip to main content

​
Goal

Each end user has a durable deposit address. When they send crypto, you credit their in-app balance after ZBX confirms the payment via signed webhooks.

​
1. Foundation

  1. Create virtual account with chains/currencies you support
  2. Store API key + request signing secret
  3. Implement webhook signature verification

​
2. On user signup

Generate a deposit address for each chain you show in the UI:
Save address → user_id → chain_id in your database.

​
3. Wallet UI

  • Show address (and QR) only for the selected network
  • Copy labels from Networks and Currencies
  • Warn that wrong-chain or wrong-token transfers may be unrecoverable

​
4. Webhook credit rule

On verified Payment.Updated (or related payment event) with a successful status:
  1. Map payment customer / reference back to your user
  2. Idempotently apply ledger credit by payment id
  3. Optionally notify the user
Never credit solely because funds appear on-chain without a platform payment event.

​
5. Balances and ops

  • Merchant balances: GET https://mapi.zbx.boomfi.xyz/v1/accounts/virtual/balances
  • Dashboard: https://merchants.zbx.boomfi.xyz/dashboard/account and transactions
  • Failed webhooks: Event History and Replay

​
6. Withdrawals / payouts (optional)

If users can cash out, use the virtual-account payout API (POST /accounts/virtual/payout/address with request signing) and apply your own risk controls.