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)

Callbacks

A callback (webhook) is the HTTP request we send to your server when a deposit arrives, so you don't have to poll. You choose its URL with callback_url in Request Wallet (VIP) or Request Ramzlink.

When we send it#

Right after a deposit is credited to your balance, once per deposit:
VIP terminal: every deposit to the terminal's addresses, in any supported token.
Ramzlink invoice: every deposit to the invoice, also partial ones, with the invoice's new status.
By then the deposit is final on our side: Inquiry already returns it.

What we send#

POST to your callback_url, body JSON, header Content-Type: application/json.
VIP terminal
{
  "terminalId": "300001",
  "trxRefId": "0x55a13a230a4db3b0d4c1e7f8a2b9d6e3f0c5a8b7d4e1f2a3b6c9d8e7f0a1b2c3",
  "callback_url": "https://api.your-exchange.com/bitycle/callback"
}
trxRefId is the transaction hash. The body has no amount or token on purpose: get them with Inquiry payment.
Ramzlink invoice
{
  "invoice": {
    "status": "SUCCESS",
    "invoice_number": "6560cdb2",
    "invoice_link": "fOdPI023YC",
    "deposits_count": 2,
    "full_name": "Alice Morgan",
    "contact_info": "",
    "token": "USDT",
    "total_deposits": "100.00000000",
    "description": "Order 58213",
    "required_amount": "100.00000000",
    "createTime": "2026-11-15T10:35:26.000Z",
    "expirationTime": "2026-11-15T12:35:26.000Z"
  }
}
invoice_link is the invoice id; confirm with Get Ramzlink Status (GET /pg/v1/ramzlink/invoice/fOdPI023YC). status: SUCCESS means fully paid.

What you answer#

Any HTTP 2xx within 10 seconds. The body is ignored.
Answer first, then do your own work (database, emails, your own API calls) in the background. If your handler takes longer than 10 seconds, we count the attempt as failed even if you processed it.

Retries#

An attempt fails when your server answers anything but 2xx, doesn't answer within 10 seconds, or can't be reached (DNS, TLS, connection refused). Then we try again:
AttemptWhen
1Right after the deposit is credited
21 minute after attempt 1 failed
310 minutes after attempt 2 failed
430 minutes after attempt 3 failed
560 minutes after attempt 4 failed (last)
Missed all five (for example during a long outage)? Send it again from the dashboard, or reconcile with Get Deposits.

Handle it safely#

1.
Don't trust the body. Callbacks are not signed, so anyone who knows your URL could call it. Always confirm with Inquiry or Get Ramzlink Status, which need your merchant code, and credit from their answer.
2.
Credit each deposit once. The same callback can arrive more than once (a retry after your server answered too late, or Send callback again). Store trxRefId with a unique constraint and skip it when it's already there. For Ramzlink, act once per invoice when it becomes SUCCESS.
3.
Map the terminal to your user: terminalId is the nounce you gave that user.
Example (Node.js, Express):
Example (PHP):

See what we sent: the dashboard#

Open the deposit in the dashboard (Transactions → the deposit). Its Callback section shows:
the callback URL,
every attempt: Delivered or Failed, the HTTP status your server answered (or the error, e.g. no answer within 10 s), and the time,
a Send callback again button: it sends the same callback right away and shows your server's answer. Use it after you fix your endpoint; there is no need to pay again.

Test it#

Use a free webhook.site URL as callback_url, make a small deposit, and see the exact request arrive there. Then point callback_url at your server (call Request Wallet again for the terminal: it keeps the addresses and replaces the URL) and use Send callback again to replay it.

Common problems on the merchant side#

What you seeUsual causeFix
Failed · no answer within 10 sYour handler does all its work before answeringAnswer 200 first, work after
Failed · HTTP 403 / 419A firewall, WAF, Cloudflare rule or CSRF protection blocks our POSTAllow our requests on that path; exclude it from CSRF checks
Failed · HTTP 404 / 405Wrong path, or the route only accepts GETCheck the URL; accept POST
Failed · HTTP 500Your code crashes, often while reading the bodyWe send JSON, not form data: parse application/json
Failed · ECONNREFUSED / ENOTFOUND / certificateURL unreachable from the internet, DNS name wrong, or expired / self-signed TLS certificateUse a public URL with a valid certificate
Arrives as a GET with an empty bodyThe URL answers with a 301/302 redirect (e.g. http:// → https://, or a missing trailing /), which turns the POST into a GETUse the final URL
Arrives twiceA retry, or Send callback againCredit once per trxRefId
Nothing at allNo callback_url set, or the deposit was not credited (for example another token than a Ramzlink invoice's)Look for the deposit in the dashboard; see Errors & FAQ
Modified at 2026-11-18 06:07:47
Previous
Concepts
Next
Errors & FAQ
Built with