Dokumentasi API
Dokumentasi integrasi API terbuka Tovanix, dibagi per layanan: Pembayaran Multirantai, Sewa Energi, SMTP API, API AI, Kartu virtual, Email, Penyimpanan objek, Verifikasi dan risiko transaksi, Akses MCP. Lab: Studio Kontrak, Simulasi Ulang Pembayaran, Laboratorium Perutean AI.
- Pembayaran Multirantai
- Sewa Energi
- SMTP API
- API AI
- Kartu virtual
- Penyimpanan objek
- Verifikasi dan risiko transaksi
- Akses MCP
USDT / USDC / ETH / TRX / BTC · TRON / EVM / Bitcoin · Tanda tangan ganda HMAC-SHA256 (pembayaran) + RSA-2048 (pembayaran keluar) · push penyelesaian 30 detik
Integrasi 3 Langkah
- 1 Daftar akun + buat aplikasi Ambil app_id dan app_key di "Aplikasi Saya" dalam konsol, lalu atur notify_url Daftar Gratis →
- 2 Implementasikan helper tanda tangan Pembayaran memakai HMAC-SHA256 (simetris), pembayaran keluar RSA-2048 (asimetris). SDK resmi membungkus keduanya dengan contoh lengkap antarbahasa.
- 3 Pilih mode dan jalankan transaksi pertama Satu-ke-satu (alamat tertaut ke pengguna, cocok untuk dompet/isi saldo) · Rotasi (alamat per pesanan, cocok untuk checkout e-commerce)
Ringkasan
Tovanix mendukung dua mode pembayaran yang dapat aktif bersamaan:
Mode Satu-ke-Satu
Pengguna menautkan alamat tetap; semua dana masuk didorong otomatis. Cocok untuk isi saldo dan penerimaan pembayaran.
- Pengguna menautkan alamat penerimaan tetap
- Push notifikasi dana masuk waktu nyata
- Mendukung pembayaran berulang
- Verifikasi tanda tangan mandiri
Mode Rotasi
Alamat penerimaan ditetapkan dinamis saat pesanan dibuat dan didaur ulang ketika kedaluwarsa. Cocok untuk pembayaran sekali pakai.
- Alokasi alamat dinamis
- Kontrol kedaluwarsa pesanan
- Konversi kurs otomatis
- Halaman checkout
Algoritme Tanda Tangan
Push satu-ke-satu memakai webhook_secret untuk tanda tangan, bukan app_key.
1. Gunakan HMAC-SHA256 dengan rahasia sebagai parameter kunci HMAC (bukan ditambahkan ke teks)
2. Tanda tangan adalah heksadesimal 64 karakter huruf kecil; perbandingan peka huruf besar/kecil
3. Saat membuat pesanan, amount harus dua desimal (mis. 100.00), timeout teks bilangan bulat; meskipun timeout tidak diberikan, tanda tangani sebagai timeout=0 (server selalu memasukkannya)
4. Kolom bernilai kosong tidak ikut dihitung dalam tanda tangan
Perlindungan Replay
Untuk mencegah replay permintaan yang disadap, permintaan bertanda tangan dapat menyertakan waktu dan nonce yang ikut ditandatangani. Tutup pesanan, tautkan/lepas alamat mewajibkannya dan mengembalikan 400 jika tidak ada; endpoint lain opsional.
/api/v1/pay/close: timestamp dan nonce wajib. /api/v1/pay/bind-address dan /api/v1/pay/unbind-address: sign_ts dan nonce wajib (kolom waktu juga menerima nama timestamp). /api/v1/pay/get-address juga memakai sign_ts, tetapi opsional. Buat pesanan, kueri pesanan, dan konfigurasi aplikasi memakai timestamp opsional: jika waktu dan nonce keduanya ada, server memeriksa rentang waktu dan nonce; jika satu atau tidak ada, hanya tanda tangan diperiksa.
timestamp harus dalam 300 detik dari waktu server; sinkronkan melalui NTP. nonce tidak boleh dipakai ulang dalam 5 menit. Waktu di luar rentang atau nonce ulang ditolak: buat/kueri pesanan HTTP 400, endpoint lain 401; kolom message menjelaskan alasan.
Tautkan Alamat
POST /api/v1/pay/bind-address
Tetapkan alamat pembayaran tetap untuk pengguna. Jika sudah tertaut, kembalikan alamat yang sama.
Kueri Penautan
POST /api/v1/pay/get-address
Kueri alamat pembayaran yang tertaut ke pengguna.
Lepas Alamat
POST /api/v1/pay/unbind-address
Lepas alamat pembayaran pengguna.
Buat pesanan
POST /api/v1/pay/create
Buat pesanan pembayaran; sistem otomatis menetapkan alamat penerimaan.
Kolom Respons
amount menerima angka atau teks: 100 atau "100". Untuk tanda tangan, selalu gunakan dua desimal, seperti "100.00".
Kueri Pesanan
GET /api/v1/pay/query
Kueri status melalui ID pesanan Anda. Parameter dikirim melalui URL Query.
Tutup Pesanan
POST /api/v1/pay/close
Tutup pesanan belum dibayar secara manual; alamat dikembalikan ke kumpulan. Hanya status=0 (menunggu) yang dapat ditutup.
Kueri Konfigurasi Aplikasi
GET /api/v1/pay/app-config
Kueri mode aplikasi, token aktif, pengaturan push, dan lainnya tanpa data sensitif.
Push Satu-ke-Satu
Saat alamat tertaut menerima transfer, sistem mengirim POST ke notify_url yang diatur.
Push ditandatangani dengan webhook_secret, dapat dilihat atau dibuat ulang di detail aplikasi.
Kolom Push
Setelah menerima, balas HTTP 200 atau {"code": 0}; jika tidak, sistem mencoba ulang hingga 10 kali dengan jeda eksponensial.
Notifikasi Callback Pesanan
Setelah pesanan rotasi dibayar, sistem mengirim callback ke notify_url.
Callback ditandatangani dengan webhook_secret, dapat dilihat atau direset di detail aplikasi.
Kolom Callback
Status 2xx apa pun dianggap terkirim; isi respons tidak diperiksa (membalas {"code": 0} dengan status selain 2xx tetap gagal). Status selain 2xx, tidak ada respons dalam 10 detik, gagal koneksi, dan pengalihan dihitung gagal; platform mencoba lagi setelah 30 detik, 1, 2, dan 5 menit, lalu setiap 10 menit, hingga 10 kali. Percobaan ulang memakai notify_id yang sama tetapi membawa sign_ts, nonce, dan tanda tangan baru — hapus duplikat berdasarkan notify_id.
Ambil Kurs Pertukaran
GET /api/v1/rate
Ambil kurs waktu nyata antara dua mata uang
Konversi Jumlah
POST /api/v1/convert
Konversi jumlah menggunakan kurs waktu nyata
Kurs Massal
GET /api/v1/rates
Kueri kurs beberapa mata uang (kode dipisahkan koma)
Semua Kurs Pertukaran
GET /api/v1/rates/all
Ambil daftar kurs semua mata uang yang didukung
Kurs Fiat
GET /api/v1/rates/fiat
Ambil semua kurs fiat berdasarkan mata uang tertentu (30+ mata uang, dikelompokkan menurut wilayah)
Status pesanan
Pesanan melewati status berikut:
Kode Error
Kode error terpadu API pembayaran (/api/v1/pay/*); kode API pembayaran keluar di bagian Referensi.
Ringkasan / Prasyarat Pembayaran Keluar
API pembayaran keluar mengirim aset yang sudah dikumpulkan di dompet pusat ke alamat luar: tanda tangan timbal balik RSA-2048 + izin IP + penyiaran tertunda + intersepsi notifikasi multisaluran + callback konfirmasi on-chain.
Hanya dana terkumpul dalam kustodi sistem dapat dibayar. Kustodi mandiri menerima langsung ke alamat Anda tanpa pengumpulan; tidak ada saldo menunggu pembayaran keluar sehingga API ini tidak dapat dipakai.
Aktifkan dalam 4 Langkah
- Buka Pembayaran Multirantai → Pembayaran Keluar API di konsol
- Buat pasangan RSA-2048 lokal dan unggah kunci publik
- Wajib minimal satu IP di daftar izin; opsional alamat, batas per transaksi, dan jeda
- Aktifkan utama; platform membuat pasangan untuk akun. Salin publik platform untuk verifikasi callback.
Tanda Tangan · RSA-2048 (Pembayaran Keluar)
Semua /api/v1/withdraw* wajib header berikut. Berbeda HMAC simetris, RSA asimetris; platform hanya menyimpan publik Anda, jadi risiko hanya bila privat bocor.
- X-API-Key — Kunci API platform dari Alat & Pengaturan → Pengelolaan API, wajib kemampuan withdraw
- X-Timestamp — Unix milidetik saat ini; selisih server ≤60 detik
- X-Nonce — nonce uuid sekali pakai, tidak ulang dalam 5 menit
- X-Withdraw-Signature — RSA-PKCS1v15-SHA256(caller_private_key, signString), Base64
Aturan Gabung Teks Tanda Tangan
BODY adalah badan HTTP asli, JSON persis tanpa serialisasi ulang. Untuk GET, kosong.
Selain tanda tangan RSA tingkat akun dan daftar izin IP tingkat akun di atas, kunci API yang dipakai wajib memiliki kemampuan withdraw dan tunduk pada daftar putih IP sumbernya sendiri: kemampuan yang tidak ada mengembalikan 403 / 4032, dan IP sumber di luar daftar putih kunci mengembalikan 403 / 4033. Kedua pemeriksaan berlaku untuk /api/v1/withdraw, /api/v1/balance/withdrawable, dan /api/v1/fee/quote. Kunci yang sudah ada sebelum perubahan ini otomatis memiliki kemampuan withdraw dan tidak terpengaruh; untuk kunci baru, pilih kemampuan tersebut di Alat dan pengaturan → Pengelolaan API. Anda dapat memeriksa kemampuan kunci dengan GET /api/v1/whoami (dipanggil dengan X-API-Key + X-Secret-Key atau tanda tangan HMAC).
Callback Hasil Pembayaran Keluar
Anda dapat mengirim callback_url di body saat membuat pesanan; setelah pencairan selesai / gagal / dibatalkan, platform mengirim hasilnya dengan POST ke URL tersebut.
- Callback ditandatangani privat platform pada header X-Platform-Signature
- Sisi Anda wajib memverifikasi tanda tangan dengan kunci publik platform (dapat disalin di halaman pengaturan); algoritma verifikasinya sama dengan arah permintaan
- Gagal dicoba ulang 1m / 5m / 30m / 2h / 6h / 24h, total 6 kali, lalu manual
- Wajib HTTP 2xx, selain itu gagal
Header
- X-Timestamp — Timestamp unix saat ini dalam milidetik
- X-Platform-Signature — Base64(RSA-PKCS1v15-SHA256(kunci privat platform, string tanda tangan))
Aturan Gabung Teks Tanda Tangan
PATH adalah bagian path dari callback_url (tanpa host dan query string), BODY adalah isi permintaan asli yang diterima — jangan diserialisasi ulang. Verifikasi dengan kunci publik platform dari halaman pengaturan.
status bernilai completed / failed / failed_onchain / cancelled; jumlah dan biaya berupa string; created_at dan completed_at dalam detik unix, 0 jika belum ada waktu selesai. Body tidak berubah antar percobaan ulang pesanan yang sama — hapus duplikat berdasarkan order_id.
Mulai Pembayaran Keluar
POST /api/v1/withdraw
Pesanan pending menunggu jeda sebelum worker menyiarkan. Saat menunggu, dapat dijeda/dipercepat/dibatalkan di konsol.
Deskripsi Kolom
- chain — string — Ya — tron / eth / bsc / polygon / arbitrum / base / optimism / avax / xlayer / btc
- symbol — string — Ya — USDT / TRX / ETH, dan lainnya
- amount — string — Ya — Hingga 18 desimal; gunakan teks untuk menghindari error floating-point
- to_address — string — Ya — Alamat tujuan, wajib ditambahkan jika daftar izin alamat aktif
- memo — string — Tidak — Deskripsi ≤500 karakter, dikirim bersama notifikasi pengguna
- callback_url — string — Tidak — URL hasil, tidak ada callback jika kosong
- request_id — string — Sangat disarankan — Kunci idempotensi, sama pada akun sama menghasilkan pesanan asal; jika rantai, simbol, alamat, atau jumlah berbeda, dikembalikan 409 dan tidak ada pesanan dibuat Tanpa ini tidak ada perlindungan idempotensi: mengulang setelah timeout atau respons 5xx akan membuat pembayaran nyata kedua.
Kolom Respons
- order_id — string — ID penarikan untuk Kueri Penarikan Tunggal
- status — string — Status sama dengan status_label kueri. Baru pending: saldo dipotong, menunggu jeda risiko/broadcast. request_id sama mengembalikan status sebenarnya, mungkin completed/failed.
- amount — string — Jumlah penarikan teks
- fee — string — Estimasi biaya snapshot saat pesan
- fee_mode — string — in_amount: dari jumlah, diterima=amount−fee, saldo=amount; out_amount: terpisah, diterima=amount, saldo=amount+fee
- delayed_until — string | null — Waktu penyiaran terencana setelah jeda risiko; null tanpa jeda
Kueri Status Satu Pembayaran Keluar
GET /api/v1/withdraw/:id
Detail pesanan untuk polling; callback tetap disarankan.
Kolom Respons
- id — string — ID pesanan penarikan
- request_id — string — Kunci idempotensi yang dikirim
- chain / symbol — string — Rantai / simbol token
- amount / expected_fee / fee_mode — string — Jumlah / biaya snapshot / mode biaya in_amount, out_amount
- to_address — string — Alamat tujuan
- memo — string — Memo TAG/Memo
- status / status_label — int / string — Kode dan label status, lihat Status Pesanan
- tx_hash — string — Hash on-chain setelah disiarkan
- fail_reason — string — Alasan saat gagal
- delayed_until / broadcast_at / confirmed_at / paused_at / cancelled_at — string | null — Waktu rencana/broadcast/konfirmasi/jeda/batal; null jika belum
- callback_url / callback_retry — string / int — URL callback / jumlah percobaan
- callback_state — string — Status callback: pending = belum dipanggil atau sedang dicoba ulang, success = 2xx diterima, giveup = percobaan ulang habis, no_url = callback tidak dikonfigurasi
- created_at — string — Waktu pembuatan
Kueri Saldo Tersedia
GET /api/v1/balance/withdrawable
Saldo terkumpul menunggu pembayaran keluar per rantai/aset; hanya bagian ini dapat dipakai API.
Struktur dua tingkat: chain → simbol token → saldo yang dapat ditarik (string); hanya entri dengan saldo lebih besar dari 0 yang dikembalikan.
Perkiraan biaya
Biaya tetap prapotong admin per rantai/token, seperti OKX.
Kolom Respons
- chain / symbol / amount — string — Parameter asal: chain / symbol / amount
- fee_amount — string — Jumlah biaya
- fee_asset — string — Aset penyelesaian biaya
Contoh cURL Lengkap
Alur tanda tangan dan permintaan lengkap, salin ke terminal untuk mencoba.
Status Pesanan · Pembayaran Keluar
Mesin status pending → broadcasted → completed / failed_onchain; di antara bisa paused / cancelled / failed.
- 0 — pending — Saldo dipotong, menunggu jeda/belum disiarkan
- 1 — completed — Konfirmasi on-chain berhasil, memenuhi syarat callback
- 2 — failed — Gagal sebelum broadcast, saldo dikembalikan
- 3 — broadcasted — Disiarkan, menunggu konfirmasi
- 4 — failed_onchain — Gagal on-chain, revert/tidak ditambang lama, saldo kembali
- 5 — paused — Dijeda manual pengguna, dapat lanjut/batal
- 6 — cancelled — Dibatalkan manual pengguna, saldo kembali
- 7 — broadcasting — Menyiarkan, sementara untuk mencegah siaran ganda
Kode Error · API Pembayaran Keluar
- 400 — Parameter invalid / saldo kurang / jumlah di luar batas rantai-token / alamat invalid
- 401 — Kunci invalid / waktu meleset / nonce terpakai / tanda tangan gagal
- 403 — Pencairan via API belum diaktifkan untuk akun / IP tidak ada di daftar izin akun; atau kunci API tidak memiliki kemampuan withdraw (kode 4032) atau IP sumber tidak ada di daftar putih kunci tersebut (kode 4033)
- 404 — Pesanan tidak ditemukan
- 429 — Terlalu banyak, maksimal 10/detik/akun. Retry-After: 1; ulang sedetik dengan request_id sama.
- 5xx — Error platform dapat diulang; pakai request_id sama untuk idempotensi
Catatan Keamanan Pembayaran Keluar
- Jaga privat lokal; kebocoran memungkinkan pembayaran atas nama Anda
- Anda wajib mengonfigurasi daftar izin IP sebelum mengaktifkan pencairan via API (wajib); IP di luar daftar izin ditolak meskipun tanda tangannya valid
- Disarankan izin alamat dan daftarkan tujuan dikenal dahulu
- Setelah 2FA aktif, gunakan di konsol untuk mempercepat/membatalkan selama jeda
- Untuk jumlah besar, gunakan jeda beberapa jam agar notifikasi memberi waktu intersepsi manual
Halaman terkait: Pembayaran Kripto Multichain · API SMTP terpadu · Layanan AI
Memuat…