Руководство по интеграции

Ваш сервер создаёт платёж через API, а kokiwa присылает вебхук, когда деньги поступают. Средства идут прямо в ваш кошелёк в блокчейне; kokiwa их не хранит.

Сначала пройдите весь процесс в тестовой сети с бесплатными тестовыми токенами, см. Тестирование. Что видят пользователи, можно посмотреть в разделе Попробовать оплату.

Подготовка

Всё это делается в кабинете мерчанта.

РегистрацияПодтвердите почту, подключите приложение-аутентификатор и сохраните коды восстановления.
Создайте проектПроект соответствует одному вашему продукту или сайту, и у него свои адреса получения, API-ключи и вебхуки.
Настройте приёмНа странице проекта «Настройки приёма» выберите сети, способы приёма и токены, затем зарегистрируйте адрес получения в каждой сети с помощью кошелька. Адрес записывается в блокчейн, и изменить его может только кошелёк, который его зарегистрировал. Регистрация требует немного газа; один кошелёк может зарегистрировать все EVM-сети.
Создайте API-ключКлюч показывается один раз. Храните его в переменной окружения на сервере, а не во фронтенде или приложении.
Настройте вебхукНа странице «Вебхуки» укажите https-адрес, сохраните секрет подписи и нажмите «Отправить тестовое событие», чтобы проверить доставку.

Выберите способ приёма

	Платёж	Адрес пополнения
Подходит для	Заказов: фиксированная сумма, одна оплата	Пополнения счёта: сумму выбирает пользователь, сколько угодно раз
Адрес	Один на платёж, выводится из работы после истечения срока	Один на пользователя, постоянный
Как платит пользователь	Кошельком на странице оплаты; в BNB Chain можно также перевести на отдельный адрес	Переводом с кошелька или биржи
Сети	Все 8	BNB Chain
gas	За оплату кошельком платит пользователь; сбор переводов оплачивает kokiwa	За перевод платит пользователь; сбор оплачивает kokiwa

Можно использовать оба способа.

Платёж

Создайте платёж, когда пользователь оформляет заказ, и откройте для него полученный checkout_url. Запрос ниже предлагает все сети, где проект принимает USDT, а пользователь выбирает одну.

curl https://api.kokiwa.com/v1/payment_intents \
  -H "Authorization: Bearer $KOKIWA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-10086" \
  -d '{
    "currency": "USDT",
    "amount": "25.00",
    "customer": "user_42",
    "metadata": { "order_id": "10086" },
    "success_url": "https://your-shop.com/orders/10086"
  }'

Адрес пополнения

В customer укажите ID пользователя в вашей системе. Повторные вызовы для того же пользователя возвращают тот же адрес.

curl https://api.kokiwa.com/v1/deposit_addresses \
  -H "Authorization: Bearer $KOKIWA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "customer": "user_42" }'

Подтверждение оплаты

Когда платёж подтверждён в блокчейне, kokiwa отправляет вебхук. Зачисляйте средства только по вебхукам, а не потому, что пользователь вернулся на success_url.

Платёж: при payment_intent.paid отметьте заказ как оплаченный.
Адрес пополнения: при deposit.confirmed увеличьте баланс data.deposit.customer.

Проверяйте подпись каждого события и отсеивайте дубликаты по id события, см. Вебхуки.

Суммы

Все суммы — это строки в единицах токена, например "25.00" или "24.9125", в запросах, ответах и вебхуках, поэтому пересчитывать по сетям не нужно. Суммы сохраняют полную точность блокчейна, поэтому число знаков после запятой может быть разным. Не считайте суммы с плавающей точкой.

Возвраты

Средства уже в вашем кошельке, поэтому в kokiwa нет метода возврата и платёж нельзя отменить. Для возврата отправьте средства пользователю со своего адреса получения. Попросите у пользователя адрес для возврата и не используйте transaction.from: при выводе с биржи это адрес биржи. Комиссия не возвращается.

Проверка перед запуском

API-ключи есть только на сервере, их нет в репозиториях и логах.
Вебхуки проверяют подпись, а повторное событие не зачисляется дважды.
Платежи создаются с Idempotency-Key, поэтому сетевой повтор не создаст второй платёж.
payment_intent.paid_late обрабатывается, поэтому оплата после истечения срока не потеряется.
Адреса получения зарегистрированы в основной сети, и вы перешли на ключ, начинающийся с sk_live_.
Для адреса получения есть резервная копия сид-фразы.

Далее: Тестирование