Skip to main content
Потрібна підписка Silver або вище — і щоб подати заявку, і для кожного авторизованого виклику. Якщо підписка власника ключа спливає, проєкт заморожується до її поновлення.
REST API, що дає вашому застосунку працювати з балансом Vito користувача просто з Discord: читати його, списувати, нараховувати або переказувати між користувачами. Усі ендпоїнти повертають JSON і версіоновані під /v1.
Vito ніколи не переходить у реальні гроші й не береться з них. Він рухається лише між балансами Vetox.

Отримання доступу

Доступ надається окремо для кожного проєкту. Потрібні всі чотири умови:
1

Активна підписка, Silver або вище

Перевіряється при кожному виклику, а не лише під час схвалення.
2

Схвалена заявка розробника

Подається зі сторінки Vito API у вашій панелі. Команда Vetox розглядає її вручну.
3

Прийняті умови для розробників API

Підтверджуються під час подання заявки.
4

Scopes, потрібні вашому проєкту

Надаються командою Vetox відповідно до вашого опису.
Пишіть конкретно, що ви створюєте і як зберігатимете ключ. Відхиляють саме розпливчасті заявки.

Scopes

Автентифікація

Надсилайте секретний ключ як Bearer-токен:
Два необовʼязкові рівні додатково захищають проєкт:
  • Список дозволених IP — обмежує виклики конкретними IP-адресами серверів
  • Ліміти частоти — стелі на проєкт, що зростають разом із рівнем підписки власника

Ключі, ротація та зберігання

Ключ і секрет підпису показуються рівно один раз. Після схвалення у вас є вікно у 7 днів, щоб розкрити їх на вкладці API-ключів. Vetox зберігає лише хеш і не може показати їх знову — якщо пропустите вікно, доведеться зробити ротацію.
  • Тримайте ключ лише на сервері — хто ним володіє, може списувати кошти ваших користувачів
  • Робіть ротацію на вкладці API-ключів. Попередній ключ працює ще 24 години — пільговий період, щоб викотити оновлення без простою
  • Секрет підпису вебхуків ротується окремо, з власним 24-годинним перекриттям
  • У разі витоку негайно зробіть ротацію

Списання з користувача

Сам лише ключ не може перемістити Vito користувача. Кожне списання вимагає підтвердження користувачем PIN-кодом його гаманця, на vetox.io — ніколи всередині вашого застосунку й ніколи всередині Discord.
1

Ваш застосунок викликає POST /v1/deduct

З користувачем, сумою, вихідним guildId і даними товару.
2

Vito повертає confirmUrl

Підтвердження в очікуванні, дійсне 10 хвилин. Користувач також отримує ПП.
3

Користувач підтверджує PIN-кодом

На vetox.io.
4

Vito проводить розрахунок і сповіщає

Баланс списується, транзакція записується, і надсилається підписаний вебхук, якщо він у вас налаштований.
5

Ваш застосунок перевіряє й завершує

Перевірте підпис, потім відкрийте доступ до вмісту або видайте товар.
Завершуйте свою дію лише за confirmation.completed — ніколи за відповіддю /deduct. На цьому етапі списання ще не остаточне.

Параметри запиту — /v1/deduct

Нарахування користувачеві

POST /v1/add нараховує Vito користувачеві з вашого власного балансу — для нагород або повернень. Ті самі поля, що й у /deduct, окрім guildId і product.
На відміну від списання, нарахування не має кроку підтвердження — розрахунок відбувається одразу. Потрібен scope credit:create і достатній баланс, інакше виклик поверне 402 VITO_INSUFFICIENT_OWNER_FUNDS.

Комісії

Кожне списання надходить вам за вирахуванням комісії платформи — за тією ж шкалою, що й перекази Vito всередині застосунку, залежно від вашого рівня підписки:
Суми 5 Vito й менше не обкладаються комісією, а нарахування через /v1/add не обкладаються нею ніколи.

Вебхуки

Додайте одну або кілька https-адрес зворотного виклику на вкладці налаштувань. Vito надсилає підписаний POST, щойно підтвердження досягає кінцевого стану.
Вебхуки надсилаються, лише якщо у проєкту є і адреса зворотного виклику, і секрет підпису. Розкрийте секрет (whsec_…) один раз на вкладці API-ключів.

Перевірка підпису

Кожна доставка містить заголовок X-Vito-Signature:
Кожну доставку супроводжують ще два заголовки — використовуйте X-Vito-Event-Id як ключ дедуплікації, бо повторна спроба надсилає той самий ідентифікатор:
Під час ротації секрету підпису заголовок містить кілька підписів, найновіший першим:
Приймайте доставку, якщо збігається будь-який із h1. Код перевірки, що читає лише перший, відхилятиме всі вебхуки, доки не викотить новий секрет, — а це зводить нанівець весь сенс 24-годинного перекриття.
Перерахуйте HMAC за <ts>:<rawBody> вашим секретом підпису і порівняйте за сталий час.
Перевіряйте за сирим тілом запиту, до будь-якого розбору JSON чи middleware, що його перепише.

Події

Пʼять типів подій з однаковою структурою корисного навантаження. Поле data.status містить результат.
Вебхуки повторюються 5 разів зі зростаючою затримкою. Швидко відповідайте 2xx, а видачу виконуйте асинхронно.

Коди помилок

Кожна відповідь загорнута в конверт. Успіх несе data, помилка — error, і ніколи обидва разом:
Кожен код має префікс VITO_. Порівнюйте рядок цілком — голий RATE_LIMITED чи FORBIDDEN ніколи не приходить у відповіді.

Ліміти частоти

Також діє ліміт на один IP, що дорівнює половині вашої хвилинної квоти, але не менш ніж 30.
Під навантаженням ендпоїнти запису відмовляють «закрито» — списання відхиляється, щоб не ризикувати подвійною витратою. Ендпоїнти читання відмовляють «відкрито». Вважайте відхилений запис таким, що «не стався», і повторіть його.
Надсилайте заголовок Idempotency-Key, щоб безпечно уникати дублів при повторних спробах.

Ендпоїнти

Обмеження

  • Підтвердження спливають через 10 хвилин — вважайте непідтверджені запити покинутими
  • amount має бути додатним цілим числом
  • metadata обмежена 10 ключами
  • Ліміти на транзакцію і на день задає команда Vetox; вони показані лише для читання на вкладці налаштувань

Чек-лист безпеки

API-ключу й секрету підпису не місце в клієнтському коді. У разі витоку будь-якого з них негайно зробіть ротацію.
Звіряйте підпис із сирим тілом запиту й відхиляйте доставки, старші за ~5 хвилин.
Ніколи не видавайте товар за відповіддю /deduct — списання остаточне лише за confirmation.completed.
Запитуйте лише ті scopes, які справді використовуєте, і ввімкніть список дозволених IP.

Усунення несправностей

Підписка власника спливла. Вона перевіряється при кожному виклику.
Відновити його неможливо — зберігається лише хеш. Зробіть ротацію, щоб отримати новий.
Приймайте обидва секрети протягом 24-годинного перекриття.
Користувач його не підтвердив. Підтвердження спливають через 10 хвилин.
Проєкту потрібні і адреса зворотного виклику, і секрет підпису. З одним із двох нічого не доставляється.
Це розрахункова комісія. Використовуйте суми 5 Vito й менше, щоб її уникнути, або закладайте її в ціну.
/v1/add фінансується з вашого власного балансу, а не створюється з нічого. Поповніть його.

Vito

Баланси, PIN-код і комісії.

Запити на оплату

Що бачить користувач, коли ви списуєте з нього.