Vito API dan Pembelian

Membutuhkan Keanggotaan Silver atau lebih tinggi — baik untuk mendaftar maupun untuk setiap panggilan terautentikasi. Jika Keanggotaan pemilik kunci berakhir, proyek dibekukan sampai ia berlangganan lagi.

REST API yang memungkinkan aplikasimu bekerja dengan saldo Vito seorang pengguna dari dalam Discord — membacanya, menagihnya, menambahkannya, atau memindahkannya antar pengguna. Semua endpoint mengembalikan JSON dan diberi versi di bawah /v1.

Vito tidak pernah berpindah ke atau dari uang sungguhan. Ia hanya bergerak antar saldo Vetox.

Mendapatkan akses

Akses diberikan per proyek. Kamu memerlukan keempatnya:

Keanggotaan aktif, Silver atau lebih tinggi

Diperiksa pada setiap panggilan, bukan hanya saat persetujuan.

Pengajuan pengembang yang disetujui

Dikirim dari halaman Vito API di dasbormu. Ditinjau secara manual oleh tim Vetox.

Ketentuan Pengembang API yang disetujui

Disetujui saat kamu mengirim pengajuan.

Scope yang dibutuhkan proyekmu

Diberikan oleh tim Vetox berdasarkan apa yang kamu jelaskan.

Jelaskan secara konkret apa yang kamu bangun dan bagaimana kamu menyimpan kuncinya. Pengajuan yang samar-samar itulah yang ditolak.

Scope

Scope	Memberi izin
`balance:read`	Membaca saldo Vito seorang pengguna
`deduct:create`	Menagih saldo seorang pengguna
`credit:create`	Menambahkan Vito ke pengguna, didanai dari saldomu sendiri
`transfer:create`	Memindahkan Vito antara dua pengguna
`transactions:read`	Menampilkan dan membaca transaksi proyekmu

Autentikasi

Kirim kunci rahasiamu sebagai token Bearer:

Authorization: Bearer vito_live_xxxxxxxxxxxxxxxx

Dua lapisan opsional memperkuat proyek lebih jauh:

Daftar IP yang diizinkan — membatasi panggilan ke IP server tertentu
Batas laju — plafon per proyek yang naik seiring tingkat Keanggotaan pemilik

Kunci, rotasi, dan penyimpanan

Kunci dan secret penandatanganan ditampilkan tepat satu kali. Setelah disetujui kamu punya jendela 7 hari untuk mengungkapkannya di tab kunci API. Vetox hanya menyimpan hash dan tidak bisa menampilkannya lagi — jika terlewat, kamu harus melakukan rotasi.

Simpan hanya di sisi server — siapa pun yang memegangnya bisa menagih penggunamu
Rotasi dari tab kunci API. Kunci sebelumnya tetap berfungsi selama masa tenggang 24 jam agar kamu bisa merilis tanpa waktu henti
Secret penandatanganan webhook dirotasi terpisah, dengan tumpang tindih 24 jam tersendiri
Jika bocor, segera rotasi

Menagih pengguna

Kuncimu saja tidak bisa memindahkan Vito seorang pengguna. Setiap penagihan mengharuskan pengguna menyetujuinya dengan PIN dompetnya, di vetox.io — tidak pernah di dalam aplikasimu maupun di dalam Discord.

Aplikasimu memanggil POST /v1/deduct

Dengan pengguna, jumlah, guildId asal, dan detail barang.

Vito mengembalikan confirmUrl

Konfirmasi tertunda, berlaku 10 menit. Pengguna juga menerima DM.

Pengguna menyetujui dengan PIN-nya

Di vetox.io.

Vito menyelesaikan dan memberi tahu

Saldo dipotong, transaksi dicatat, dan webhook bertanda tangan dikirim jika kamu sudah mengaturnya.

Aplikasimu memverifikasi dan menyelesaikan

Periksa tanda tangannya, lalu buka kontennya atau kirim barangnya.

Selesaikan tindakanmu hanya pada confirmation.completed — jangan pernah pada respons /deduct. Pada titik itu penagihan belum final.

Parameter permintaan — `/v1/deduct`

Bidang	Wajib	Catatan
`discordId`	Ya	ID Discord pengguna — snowflake 17–20 digit
`amount`	Ya	Bilangan bulat positif
`guildId`	Ya	Server Discord tempat penagihan berasal. Setiap penagihan harus berasal dari sebuah server
`reason`	Tidak	Hingga 256 karakter. Ditampilkan ke pengguna dan dikembalikan di webhook
`merchantRef`	Tidak	Referensimu sendiri, hingga 128 karakter. Gunakan untuk mencocokkan webhook dengan catatanmu
`product`	Tidak	`{ type, name, description?, imageUrl? }` — tampil di halaman konfirmasi dan DM
`imageUrl`	Tidak	Harus `https://`
`metadata`	Tidak	Hingga 10 pasangan kunci/nilai teks, diteruskan apa adanya

Menambah saldo pengguna

POST /v1/add menambahkan Vito ke pengguna dari saldomu sendiri — untuk hadiah atau pengembalian dana. Bidang yang sama dengan /deduct kecuali guildId dan product.

Berbeda dari penagihan, penambahan tidak punya langkah konfirmasi — langsung diselesaikan. Membutuhkan scope credit:create dan saldo yang cukup, atau panggilan mengembalikan 402 VITO_INSUFFICIENT_OWNER_FUNDS.

Biaya

Setiap penagihan diselesaikan kepadamu dikurangi biaya platform — skema yang sama dengan transfer Vito di dalam aplikasi, berdasarkan tingkat Keanggotaan kamu:

Keanggotaanmu	Biaya
Normal, Silver, Gold	7%
Platinum	6%
Diamond	5%

Jumlah 5 Vito atau kurang bebas biaya, dan penambahan lewat /v1/add selalu bebas biaya.

Webhook

Tambahkan satu atau beberapa URL callback https di tab pengaturan. Vito mengirim POST bertanda tangan setiap kali sebuah konfirmasi mencapai keadaan akhir.

Webhook hanya terkirim jika proyekmu punya sekaligus URL callback dan secret penandatanganan. Ungkapkan secret (whsec_…) satu kali dari tab kunci API.

Memverifikasi tanda tangan

Setiap pengiriman membawa header X-Vito-Signature:

X-Vito-Signature: ts=<unix>;h1=<hex>

Dua header lain menyertai setiap pengiriman — gunakan X-Vito-Event-Id sebagai kunci deduplikasi, karena percobaan ulang mengirim id yang sama:

Header	Berisi
`X-Vito-Event-Id`	Id tetap untuk peristiwa ini — sama di semua percobaan ulang
`X-Vito-Event-Type`	Misalnya `confirmation.completed`

Selama rotasi secret penandatanganan, header membawa lebih dari satu tanda tangan, yang terbaru lebih dulu:

X-Vito-Signature: ts=<unix>;h1=<baru>;h1=<lama>

Terima pengiriman jika salah satu h1 cocok. Verifikator yang hanya membaca yang pertama akan menolak setiap webhook sampai ia merilis secret baru — dan itu justru meniadakan seluruh tujuan tumpang tindih 24 jam.

Hitung ulang HMAC atas <ts>:<rawBody> dengan secret penandatangananmu dan bandingkan dalam waktu konstan.

const crypto = require('crypto');

function verify(rawBody, header, secret) {
  const parts = header.split(';');
  const ts = parts.find(p => p.startsWith('ts='))?.slice(3);
  const sigs = parts.filter(p => p.startsWith('h1=')).map(p => p.slice(3));
  if (!ts || sigs.length === 0) return false;

  // Reject anything older than ~5 minutes — replay protection.
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;

  const expected = Buffer.from(
    crypto.createHmac('sha256', secret).update(`${ts}:${rawBody}`).digest('hex'),
  );

  // Any matching signature is valid — a rotation emits several.
  return sigs.some(sig => {
    const actual = Buffer.from(sig);
    // timingSafeEqual throws when the lengths differ, so check first.
    return (
      actual.length === expected.length && crypto.timingSafeEqual(actual, expected)
    );
  });
}

Verifikasi terhadap body mentah, sebelum parsing JSON atau middleware menulis ulangnya.

Peristiwa

Lima jenis peristiwa, semuanya berbagi satu bentuk payload. data.status membawa hasilnya.

Peristiwa	Arti
`confirmation.completed`	Disetujui dan ditagih. Membawa `transactionId`. Selesaikan tindakanmu di sini
`confirmation.failed`	Tidak bisa diselesaikan — saldo kurang atau galat internal. Membawa `failureReason`
`confirmation.expired`	Tidak dikonfirmasi dalam 10 menit. Tidak ada Vito yang berpindah
`confirmation.cancelled`	Pengguna membatalkan. Tidak ada Vito yang berpindah
`credit.completed`	Sebuah `/add` yang didanai pemilik telah diselesaikan. Langsung terpicu — tanpa langkah konfirmasi

Webhook dicoba ulang 5 kali dengan jeda menaik. Balas 2xx dengan cepat dan lakukan pemenuhanmu secara asinkron.

Kode galat

Setiap respons dibungkus. Keberhasilan membawa data, kegagalan membawa error, tidak pernah keduanya:

{
  "success": false,
  "error": {
    "type": "Forbidden",
    "message": "API key lacks the required scope for this operation.",
    "code": "VITO_INSUFFICIENT_SCOPE"
  },
  "requestId": "…",
  "timestamp": 1735161600000
}

Setiap kode berawalan VITO_. Cocokkan seluruh stringnya — RATE_LIMITED atau FORBIDDEN polos tidak pernah muncul di respons.

Kode	Status	Arti
`VITO_VALIDATION_ERROR`	400	Sebuah bidang hilang atau salah format
`VITO_INVALID_AMOUNT`	400	`amount` bukan bilangan bulat positif
`VITO_AMOUNT_LIMIT_EXCEEDED`	400	Melebihi plafon per transaksimu
`VITO_DAILY_VOLUME_EXCEEDED`	400	Panggilan ini akan melewati plafon volume harianmu
`VITO_SELF_TRANSFER`	400	Pengirim dan penerima adalah pengguna yang sama
`VITO_INVALID_API_KEY`	401	Kunci hilang, salah bentuk, dicabut, atau tidak dikenal
`VITO_INSUFFICIENT_FUNDS`	402	Saldo pengguna tidak mencukupi penagihan
`VITO_INSUFFICIENT_OWNER_FUNDS`	402	Saldo kamu terlalu rendah untuk mendanai `/add`
`VITO_INSUFFICIENT_SCOPE`	403	Kunci tidak punya scope yang diminta endpoint
`VITO_IP_NOT_ALLOWED`	403	IP pemanggil tidak ada di daftar yang diizinkan
`VITO_OWNER_MEMBERSHIP_INACTIVE`	403	Keanggotaan pemilik berakhir — dibekukan sampai berlangganan lagi
`VITO_GUILD_NOT_ALLOWED`	403	`guildId` tidak ada di daftar server yang diizinkan proyek
`VITO_TOS_NOT_ACCEPTED`	403	Ketentuan pengembang belum disetujui, atau ada versi lebih baru yang menunggu
`VITO_PROJECT_FROZEN`	403	Dibekukan — biasanya karena Keanggotaan pemilik berakhir
`VITO_PROJECT_SUSPENDED`	403	Ditangguhkan oleh tim Vetox
`VITO_PROJECT_BANNED`	403	Diblokir oleh tim Vetox
`VITO_USER_BLACKLISTED`	403	Pengguna dilarang melakukan operasi Vito
`VITO_ACCOUNT_LOCKED`	403	Dompet pengguna terkunci setelah percobaan PIN yang gagal
`VITO_USER_NOT_FOUND`	404	Tidak ada akun Vito untuk ID Discord itu
`VITO_CONFIRMATION_NOT_FOUND`	404	Token konfirmasi tidak dikenal
`VITO_IDEMPOTENCY_CONFLICT`	409	`Idempotency-Key` sama, body berbeda
`VITO_IDEMPOTENCY_IN_PROGRESS`	409	Permintaan identik masih berjalan — coba lagi sebentar
`VITO_CONFIRMATION_ALREADY_PROCESSED`	409	Konfirmasi itu sudah mencapai keadaan akhir
`VITO_KEY_ROTATION_IN_PROGRESS`	409	Rotasi sudah berjalan
`VITO_CONFIRMATION_EXPIRED`	410	Jendela 10 menit sudah lewat
`VITO_RATE_LIMITED`	429	Kurangi laju lalu coba lagi
`VITO_INTERNAL_ERROR`	500	Kegagalan tak terduga di sisi kami

Batas laju

Keanggotaan pemilik	Per menit	Per jam
Tidak ada	60	1.000
Silver atau Gold	180	5.000
Platinum atau Diamond	600	15.000

Ada juga batas per IP sebesar setengah jatah per menitmu, dengan batas bawah 30.

Saat beban tinggi, endpoint tulis gagal secara tertutup — penagihan ditolak alih-alih mempertaruhkan pembelanjaan ganda. Endpoint baca gagal secara terbuka. Perlakukan penulisan yang ditolak sebagai “tidak terjadi” lalu coba lagi.

Kirim header Idempotency-Key untuk menghindari duplikasi saat mencoba ulang.

Endpoint

Endpoint	Scope
`GET /v1/auth/verify`	apa saja
`POST /v1/auth/rotate-key`	apa saja
`GET /v1/balance/:discordId`	`balance:read`
`POST /v1/deduct`	`deduct:create`
`POST /v1/add`	`credit:create`
`POST /v1/transfer`	`transfer:create`
`GET /v1/transactions` dan `/:id`	`transactions:read`
`GET /v1/webhooks/events`	`transactions:read`

Batasan

Konfirmasi kedaluwarsa setelah 10 menit — anggap permintaan yang belum dikonfirmasi sebagai ditinggalkan
amount harus bilangan bulat positif
metadata dibatasi 10 kunci
Plafon per transaksi dan harian ditetapkan tim Vetox dan tampil hanya-baca di tab pengaturan

Daftar periksa keamanan

Simpan secret di sisi server

Kunci API dan secret penandatanganan tidak pernah pantas berada di kode klien. Rotasi segera jika salah satunya bocor.

Verifikasi setiap webhook

Periksa tanda tangan terhadap body mentah dan tolak pengiriman yang lebih tua dari ~5 menit.

Selesaikan hanya pada completed

Jangan pernah memenuhi berdasarkan respons /deduct — penagihan baru final pada confirmation.completed.

Hak seminimal mungkin

Minta hanya scope yang benar-benar kamu pakai, dan aktifkan daftar IP yang diizinkan.

Pemecahan masalah

Setiap panggilan mengembalikan tidak terotorisasi

Keanggotaan pemilik sudah berakhir. Ia diperiksa ulang pada setiap panggilan.

Saya kehilangan kunci saya

Tidak bisa dipulihkan — hanya hash yang disimpan. Rotasi untuk mendapat yang baru.

Tanda tangan webhook gagal setelah rotasi

Terima kedua secret selama tumpang tindih 24 jam.

Sebuah penagihan tidak pernah selesai

Pengguna tidak menyetujuinya. Konfirmasi kedaluwarsa setelah 10 menit.

Tidak ada webhook yang datang

Sebuah proyek butuh URL callback dan secret penandatanganan. Dengan salah satunya saja, tidak ada yang dikirim.

Vito yang masuk lebih sedikit dari yang saya tagih

Itu biaya penyelesaian. Gunakan jumlah 5 Vito atau kurang untuk menghindarinya, atau perhitungkan dalam hargamu.

402 VITO_INSUFFICIENT_OWNER_FUNDS

/v1/add didanai dari saldomu sendiri, bukan diciptakan dari ketiadaan. Isi ulang saldomu.

Vito

Saldo, PIN, dan biaya.

Permintaan pembayaran

Apa yang dilihat pengguna saat kamu menagihnya.

Utama

Utilitas

Vito

Papan Peringkat

Vito API dan Pembelian

Mendapatkan akses

Scope

Autentikasi

Kunci, rotasi, dan penyimpanan

Menagih pengguna

Parameter permintaan — `/v1/deduct`

Menambah saldo pengguna

Biaya

Webhook

Memverifikasi tanda tangan

Peristiwa

Kode galat

Batas laju

Endpoint

Batasan

Daftar periksa keamanan

Pemecahan masalah

Vito

Permintaan pembayaran

​Mendapatkan akses

​Scope

​Autentikasi

​Kunci, rotasi, dan penyimpanan

​Menagih pengguna

​Parameter permintaan — /v1/deduct

​Menambah saldo pengguna

​Biaya

​Webhook

​Memverifikasi tanda tangan

​Peristiwa

​Kode galat

​Batas laju

​Endpoint

​Batasan

​Daftar periksa keamanan

​Pemecahan masalah

Vito

Permintaan pembayaran

Mendapatkan akses

Scope

Autentikasi

Kunci, rotasi, dan penyimpanan

Menagih pengguna

Parameter permintaan — `/v1/deduct`

Menambah saldo pengguna

Biaya

Webhook

Memverifikasi tanda tangan

Peristiwa

Kode galat

Batas laju

Endpoint

Batasan

Daftar periksa keamanan

Pemecahan masalah