Руководство по интеграции с Kukuruku
Обзор системы
Kukuruku — платформа, которая связывает пользователей с мерчантами через единый кошелёк и систему аутентификации.
Компоненты
| Компонент | Описание | URL |
|---|---|---|
| Kukuruku | Сайт-агрегатор — отображает мерчантов, позволяет пополнять баланс и играть | kukuruku.win |
| KukuPay | Единый кошелёк для депозитов, выводов и управления балансом | wallet.kukuruku.win |
| KukurukuID | OAuth 2.0 сервер аутентификации на базе OpenID Connect | auth.kukuruku.win |
Базовый URL API
https://api.kukuruku.win
Все эндпоинты API используют этот базовый URL. Для локальной разработки: https://api.kukuruku.local.
Начало работы
Зарегистрируйте свой проект через личный кабинет мерчанта или свяжитесь с вашим менеджером. Набор учётных данных зависит от выбранного сценария интеграции.
Сценарии интеграции
Kukuruku поддерживает три сценария интеграции. Выберите подходящий или комбинируйте их для полной функциональности.
1. Платёжная интеграция
Принимайте депозиты от пользователей Kukuruku и обрабатывайте вывод средств на кошельки KukuPay.
Необходимые учётные данные:
| Учётные данные | Описание | Где найти |
|---|---|---|
merchant_id | Уникальный идентификатор вашего мерчанта | Личный кабинет мерчанта → Профиль (заголовок) |
secret_key | Секретный ключ для подписи API-запросов | Личный кабинет мерчанта → Профиль → «Api secret» |
Что вы получаете:
- Создание ордеров на пополнение (депозит пользователя на вашу платформу)
- Создание ордеров на выплату (вывод с вашей платформы на KukuPay)
- Получение callback'ов об изменении статуса ордера в реальном времени
- Запрос статуса ордера в любой момент
Аутентификация: HMAC-SHA512 подпись запросов — OAuth не требуется.
Руководство по платёжной интеграции
2. KukurukuID (OAuth 2.0)
Добавьте кнопку «Войти через KukurukuID» на свой сайт. Пользователи аутентифицируются через OAuth 2.0 сервер Kukuruku, и вы получаете их профильные данные.
Необходимые учётные данные:
| Учётные данные | Описание | Где найти |
|---|---|---|
client_id | OAuth 2.0 идентификатор клиента | Запросить у команды поддержки в чате |
client_secret | OAuth 2.0 секрет клиента (для серверных приложений) | Запросить у команды поддержки в чате |
redirect_uri | Одобренный URL обратного вызова вашего приложения | Согласовать с командой поддержки |
Что вы получаете:
- Single Sign-On для пользователей Kukuruku
- Доступ к профилю пользователя (имя, email, валюта)
- Authorization Code flow (серверные приложения) или PKCE (клиентские приложения)
Аутентификация: OAuth 2.0 access token — merchant_id и secret_key не требуются.
Руководство по интеграции KukurukuID
3. Автоматический вход (кнопка «Играть»)
Когда пользователь нажимает «Играть» на карточке мерчанта в Kukuruku, он автоматически перенаправляется на вашу платформу с аутентификацией и предоплаченным ордером. Этот сценарий объединяет платёжную интеграцию и KukurukuID.
Необходимые учётные данные: все из обоих сценариев выше:
| Учётные данные | Для чего | Где найти |
|---|---|---|
merchant_id | Создание ордеров | Личный кабинет мерчанта → Профиль |
secret_key | Подпись запросов | Личный кабинет мерчанта → Профиль → «Api secret» |
client_id | OAuth 2.0 аутентификация | Запросить у команды поддержки в чате |
client_secret | Обмен токенов | Запросить у команды поддержки в чате |
redirect_uri | Обратный вызов после аутентификации | Согласовать с командой поддержки |
Что вы получаете:
- Бесшовный пользовательский опыт — один клик от Kukuruku до вашей платформы
- Автоматическое создание и оплата ордера
- Автоматический вход через KukurukuID
Требования: Должны быть настроены платёжная интеграция и KukurukuID.
Руководство по интеграции автовхода
Методы аутентификации
Kukuruku API использует два метода аутентификации в зависимости от контекста:
| Метод | Когда использовать | Подробности |
|---|---|---|
| Подпись запроса | Серверные API-вызовы (ордера, callback'и) | HMAC-SHA512 подпись в заголовке signature. Подробнее |
| OAuth 2.0 токен | API-вызовы в контексте пользователя (/api/v1/me) | Bearer токен в заголовке Authorization. Подробнее |
Формат сумм
Все денежные суммы в API указываются в минимальных единицах валюты (копейки для RUB, центы для USD):
| Отображаемая сумма | Значение API | Валюта |
|---|---|---|
| 500 RUB | 50000 | RUB |
| 10.50 USD | 1050 | USD |
| 100 USDT | 10000 | USDT |
Статусы ордеров
| Статус | Описание |
|---|---|
created | Ордер создан, ожидает оплаты |
processing | Платёж обрабатывается |
paid | Платёж успешно завершён |
cancelled | Ордер отменён |
expired | Ордер истёк (не оплачен вовремя) |
failed | Платёж не удался |
Поддержка
По вопросам интеграции обратитесь к команде Kukuruku через личный кабинет мерчанта или к вашему менеджеру.