Support Manual for Integrator Teams
This manual is designed for integrator teams who are using Bitnob’s Trading API and want to support their own end customers. It includes an overview of how trading works, common customer questions, resolution templates, and best practices for integrating customer-facing support.
What Your Customers Are Doing
Your end users may:
Buy Bitcoin using USDT
Sell Bitcoin to receive USDT
See real-time rates and confirm quotes
Experience quote expirations or failed trades
Receive funds in their wallets after trade execution
As an integrator, you are their trading platform. You are responsible for presenting accurate pricing, managing quote expiry, handling errors gracefully, and explaining trade outcomes clearly.
What You Need to Know as a Platform
Bitnob provides the infrastructure and guarantees trade execution integrity
You control: quote display, confirmation UX, wallet UI, and reference mapping
You will receive webhooks for every trade.completed and trade.failed event
You are responsible for balance management and user-facing messaging
Common End-User Questions and How to Answer Them
A. “Why did my trade fail?”
Possible Causes:
The quote expired before confirmation
You didn’t have enough balance
Your app didn’t submit a valid reference or quote ID
Recommended Answer:
“We tried to execute your trade, but the rate had already expired or your balance was too low. Please refresh the quote and try again.”
B. “Why didn’t I get the amount I expected?”
Possible Causes:
The rate changed before execution (if quote was not locked)
A spread or fee was applied by your platform
Recommended Answer:
“We executed your trade at the most recent rate. If you want to lock a rate in the future, confirm your trade within 30 seconds of quote generation.”
C. “Where is my Bitcoin/USDT?”
Resolution Checklist:
Confirm trade status using /trades/:id
Verify webhook was received (trade.completed)
Show wallet transaction history or balance update in your UI
Recommended Answer:
“Your trade completed successfully. The funds were credited to your wallet. Please check your balance or wallet history.”
D. “Why do quotes expire so quickly?”
Recommended Answer:
“To ensure fair pricing, quotes are valid for only 30 seconds. This protects both you and the market from price manipulation and delay-based trading errors.”
Support Tools You Should Provide in Your App
Trade history screen with reference, status, input, and output
Wallet balance UI with clear timestamps
Expiry countdown on trade quotes
Quote refresh button
Clear success/failure messages after trade execution
Recommended Messaging Templates
Success Message
“Trade successful. You converted $100 into 225,000 sats. Funds have been credited to your Bitcoin wallet.”
Expired Quote
“This quote has expired. Please refresh to get the latest price.”
Failed Trade
“Your trade could not be completed. Please ensure you have enough balance and confirm trades before the quote expires.”
Incomplete Funds
“If you didn’t receive funds, please check your trade status or contact support with your reference ID.”
Trade Flow Reminders for Support and Product
All trades must use a unique reference
Use quoteId to lock a rate and prevent price fluctuation
Never allow users to confirm a trade after expiresAt
Rely on trade.completed webhook to confirm success
Reconcile trade outcomes with wallet crediting in your app
When to Contact Bitnob
Contact Bitnob if:
Webhooks are not arriving despite valid configuration
Trades are failing repeatedly with valid quotes and sufficient balance
Your platform cannot reconcile wallet balances post-trade
