1. Wallet as a Service(WaaS)
Bitycle Business
English
  • English
  • Turkish
  • Getting started
  • Bitycle Widget
    • introduction
    • demo
    • widgets
      • Advance Chart
      • Full Chart
      • Overview Chart
      • Fear & Greed
      • Technical Analysis
      • Mini Chart
      • Trends
      • Compare
      • Treemap
      • Ticker
      • Digest(AI)
      • News
      • Info
  • Bitycle Lab
    • Introduction
    • Wallet as a Service(WaaS)
      • Introduction
      • Quick start
      • Concepts
      • Callbacks
      • Errors & FAQ
      • Buy TRON Energy & Bandwidth
      • Tokens List
        GET
      • Get Balance
        GET
      • Request Ramzlink
        POST
      • Callback New Payment
        POST
      • Get Ramzlink Status
        GET
      • Request Wallet (VIP)
        POST
      • Inquiry payment
        POST
      • Request Withdrawal
        POST
      • Get single Withdrawal
        GET
      • Get Deposits
        GET
      • Get Withdrawals
        GET
    • Blockchain Indexer
      • introduction
      • Blockchain List
      • Contract Info
      • Get Balances
    • Security&Privacy
      • introduction
      • Check Blocked Wallets
      • Add to watch list
      • Get watch list
      • Delete from watch list
      • Get address label
      • Get address information
    • Node as a Service(NaaS)
      • introduction
    • Tokenization
      • introduction
    • Decentralized Storage(IPFS)
      • introduction
    • Hyperledger Services
      • introduction
  • Bitycle Cap
    • introduction
    • Coins
      • introduction
      • Coin List
      • Coin Info
      • Coin Price
      • coin exchange listings
    • Markets
      • introduction
      • Market Price
      • Markets Price
      • Markets List
      • Markets frame info
      • market sparklines
    • exchanges
      • introduction
      • CEX Aggregator(Buy&Sell)
        • introduction
        • get tradable markets
        • get tradable markets price
        • send otc order
        • get orders
        • get balances
      • Exchanges List
      • Exchange Info
      • Exchange Coins Listing
      • Exchange Markets Listing
  • Schemas
    • wallet
  1. Wallet as a Service(WaaS)

Errors & FAQ

Errors#

Errors come as JSON with a message (address, inquiry, invoice and balance endpoints) or an error (withdrawal and list endpoints) field. The text is not translated: match on the HTTP status and show your own message.

Every endpoint#

HTTPBodyCauseFix
422"authorization" is requiredNo Authorization headerSend Authorization: Token YOUR_MERCHANT_CODE
422`"merchant" is invalid`Wrong merchant code, or the word Token is missing (Bearer doesn't work)Copy the code from Gateway Setting; send Token + code
401{}Same, on Get Balance / Get Deposits / Get Withdrawals / Get single WithdrawalSame
422"ip address" is not validYou set a Server IP and the request came from another IP (new server, NAT, proxy, cloud function)Update Server IP in Gateway Setting, or clear it
429More than 60 requests per minute, or your daily limitSlow down; cache what doesn't change (addresses, Tokens List)
404Route Not Found! (or its translation)Wrong URL. Address, inquiry and invoice endpoints start with /pg/v1/Check the path against these docs
500Our sideRetry later; contact support if it persists

Request Wallet (VIP)#

BodyCauseFix
TerminalId is not valid.nounce outside your rangeUse a number between your Terminal (Nonce) Start and End
"merchant" is not VIPYour account has no VIP terminalsContact support
"token" must be one of [...]Unknown symbol, or lower caseUse a symbol from Tokens List with allow_deposit, e.g. USDT
"callback_url" must be a valid uriNot a full URLSend https://…

Request Ramzlink#

BodyCauseFix
"required_amount" is requiredMissing amountSend required_amount (greater than 0)
"amount" is not allowedOld field nameRename amount to required_amount
"full_name" length must be less than or equal to 30 characters longName too longShorten it
"redirect_url" is requiredMissingSend the URL where your customer should come back

Inquiry / lists#

HTTPBodyCauseFix
404transaction not found!No credited deposit with this terminalId + trxRefId on your accountUse both values exactly as the callback sent them
404ModelNotFoundUnknown invoice id or withdrawal idCheck the id
422startDate format must be yyyy-mm-ddDate filter formatUse 2026-11-15
422"perPage" must be less than or equal to 25Page too bigUse 25 or less

Request Withdrawal#

HTTPBodyCauseFix
422error: Invalid apiKeyWrong API key, or the account is not VIPCopy it from API Key Information
422error: Invalid signatureThe signed text differs from what you sentSee Invalid signature below
422error: Error code "Invalid timestamp" is not defined, …x-timestamp is more than 60 s away from our clock, or in seconds instead of millisecondsSend Date.now() milliseconds; sync your server clock (NTP)
422error: WithdrawUniqueId already exists.This id was used before: by your earlier request (a retry), or it isn't uniqueIf it's a retry: the first request was registered, find it in Get Withdrawals. Otherwise use a new, prefixed id
422error: Client widthdraw is not enable for the selected networkWithdrawal of this token is closed on this networkPick a network with allow_withdraw: true in Tokens List
422message: Insufficient balanceBalance of this token is less than amountCheck Get Balance
422message: The amount you wish to withdraw does not cover the transaction feeamount is not more than withdraw_feeWithdraw more
422message: Address is not validAddress format doesn't match the networkEVM networks need 0x…, Tron needs T…
403error: Invalid IPRequest from another IP than your Server IPUpdate Server IP

FAQ#

"My user paid, but I got no callback."#

1.
Find the deposit: in the dashboard (Transactions) or with Get Deposits ?txHash=….
2.
It's there and SUCCESS: open it and look at its Callback section. It shows every attempt and what your server answered (HTTP status, or e.g. no answer within 10 s). Fix that (see common problems), then press Send callback again.
3.
It's not there:
Check on a block explorer that the transaction succeeded and went to your address, on a network from the addresses list.
Ramzlink: another token than the invoice's, or paid more than 24 hours after the invoice was created, is not credited automatically.
Give it a few minutes: deposits are credited once our tracker reads their block.
Still missing: VIP accounts can use Recover deposit in the dashboard (network + transaction hash); others contact support with the hash.

"I got the same callback twice."#

Expected now and then: a retry after your server answered late, or someone pressed Send callback again. Credit once per trxRefId (a unique index in your database).

"The deposit was credited with 0."#

The amount was at or below the minimum deposit fee (minDeposit / min_deposit_fee), so the whole amount went to the fee. Show the minimum next to each address.

"My user sent on another network."#

Every EVM network we support uses the same address, so a deposit on any network in the addresses list is credited. For a network that isn't in the list, contact support with the hash; we can't promise recovery.

"Is there a testnet or sandbox?"#

No. Test with a small real deposit (a few USDT on BSC or Polygon). It's credited to your balance, so you can withdraw it again.

"Can I give a terminal to another user?"#

No. Addresses are permanent and watched forever: the old user's future deposits would go to the new user. Use a new terminal per user.

"Inquiry without trxRefId doesn't show an older deposit."#

That list shows only deposits whose funds are still on the address; after our regular sweep they drop out. Use Inquiry with trxRefId (always works) or Get Deposits.

"A Ramzlink customer paid only part of the amount."#

The invoice is INSUFFICIENT_PENDING while its timer runs; more deposits are added until required_amount is reached (SUCCESS). After the timer it shows INSUFFICIENT, but deposits are still added for 24 hours. What you do with a partial payment (wait, ask for the rest, refund with a withdrawal) is up to you; the partial amount is in your balance.

"Withdrawal is still PENDING or ACCEPTED."#

Withdrawals are paid in batches, usually within minutes. A PENDING one can still be cancelled in the dashboard (the amount comes back). If it stays for more than an hour, contact support with the withdrawId.

"Invalid signature."#

Order: apiKey + merchantCode + timestamp + withdrawUniqueId + amount + chain + token + walletAddress, no separators.
The same timestamp in the header and in the signed text.
amount without trailing zeros ("12.5", not "12.50"), and the same chain, token (upper case) and address spelling you send in the body.
No spaces around withdrawUniqueId.
The secret key, not the API key, as the HMAC key; output in hex.

"Where do I find my keys?"#

Dashboard → Profile → Gateway Setting: merchant code, Server IP, terminal range (VIP), API key and secret key (VIP).
Modified at 2026-11-18 05:55:03
Previous
Callbacks
Next
Buy TRON Energy & Bandwidth
Built with