Tovanix
Tovanix

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
  • Email
  • 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…