Платёжная интеграция
В этом руководстве описано создание платёжных ордеров (пополнение и выплата) через API Kukuruku. Все запросы должны включать HMAC-SHA512 подпись запроса.
Базовый URL API
https://api.kukuruku.win
Создание ордера на пополнение
POST /api/v1/orders/payins
Создаёт ордер для пополнения баланса пользователя из KukuPay на вашу платформу.
Запрос
Поля запроса
| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
merchant_id | string | Да | Идентификатор вашего мерчанта |
amount | integer | Да | Сумма в минимальных единицах валюты (копейки/центы). Должна быть > 0 |
currency | string | Да | Код валюты: RUB, USD, USDT |
order_number | string | Да | Уникальный идентификатор платежа в вашей системе |
callback_url | string | Нет | URL для получения callback'ов об изменении статуса |
redirect_success_url | string | Нет | URL для перенаправления при успешной оплате |
redirect_fail_url | string | Нет | URL для перенаправления при неудачной оплате |
customer.client_id | string | Да | Email пользователя |
Ответ 200
| Поле | Тип | Описание |
|---|---|---|
success | boolean | Результат операции |
token | string | Идентификатор ордера в системе KukuPay (UUID) |
url | string | URL для перенаправления пользователя на страницу оплаты |
После получения ответа перенаправьте пользователя на url для завершения оплаты в KukuPay.
Создание ордера на выплату
POST /api/v1/orders/payouts
Создаёт ордер на вывод средств с вашей платформы на кошелёк KukuPay пользователя.
Запрос
Поля запроса
| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
merchant_id | string | Да | Идентификатор вашего мерчанта |
amount | integer | Да | Сумма в минимальных единицах валюты. Должна быть > 0 |
currency | string | Да | Код валюты: RUB, USD, USDT |
order_number | string | Да | Уникальный идентификатор платежа в вашей системе |
callback_url | string | Нет | URL для получения callback'ов об изменении статуса |
user_email | string | Да | Email пользователя в системе Kukuruku |
Ответ 200
| Поле | Тип | Описание |
|---|---|---|
success | boolean | Результат операции |
uuid | string | Идентификатор ордера в системе KukuPay |
Ответ 400
Возвращается, когда user_email не соответствует ни одному зарегистрированному пользователю KukuPay.
Получение статуса ордера
GET /api/v1/orders/{uuid}
Получение текущего статуса ордера. Требуется подпись запроса в заголовках.
Запрос
GET /api/v1/orders/8d3cd240-dc72-4535-bf93-beed2878b593
| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
uuid | string (path) | Да | UUID ордера из ответа на создание |
Ответ 200
Поля ответа
| Поле | Тип | Описание |
|---|---|---|
id | string | Внутренний идентификатор ордера |
uuid | string | UUID ордера в KukuPay |
user_id | string | Идентификатор пользователя в Kukuruku (может быть null) |
user_email | string | Email пользователя (может быть null) |
user_phone | string | Телефон пользователя (может быть null) |
type_id | string | Тип ордера: payin или payout |
status | string | Статус: created, processing, paid, cancelled, expired, failed |
external_order_id | string | Ваш order_number из запроса на создание |
amount | integer | Сумма в минимальных единицах валюты |
currency | string | Код валюты |
created_at | string | Дата создания (ISO 8601) |
expire_at | string | Дата истечения (ISO 8601, может быть null) |
Ответ включает заголовок signature, который рекомендуется проверять для подтверждения подлинности. См. Проверка подписи.
Callback об оплате
POST {ваш_callback_url}
При изменении статуса ордера Kukuruku отправляет HTTP POST запрос на callback_url, указанный при создании ордера.
Ваш сервер должен ответить HTTP 200 с телом {"success": true}. При неудачном callback'е Kukuruku повторит попытку с экспоненциальной задержкой.
Запрос callback'а
Поля callback'а
| Поле | Тип | Описание |
|---|---|---|
uuid | string | UUID ордера в KukuPay |
type | string | Тип ордера: payin или payout |
status | string | Статус: paid, cancelled, expired, failed |
order_number | string | Ваш идентификатор платежа |
amount | string | Сумма в минимальных единицах валюты (строка в callback'ах) |
currency | string | Код валюты |
user_id | string | Идентификатор пользователя в Kukuruku |
user_email | string | Email пользователя — используйте для привязки к клиенту |
user_phone | string | Телефон пользователя (может быть null) |
created_at | string | Дата создания (ISO 8601) |
updated_at | string | Дата последнего обновления (ISO 8601) |
finished_at | string | Дата завершения (ISO 8601, может быть null) |
Ожидаемый ответ
Всегда проверяйте заголовок signature во входящих callback'ах. См. Проверка подписи.
Схема интеграции
Пополнение (Payin)
1. Пользователь инициирует пополнение на вашем сайте
2. Ваш сервер → POST /api/v1/orders/payins (с подписью)
3. Kukuruku возвращает { url, token }
4. Перенаправьте пользователя на url (страница оплаты KukuPay)
5. Пользователь завершает оплату в KukuPay
6. Kukuruku → POST {callback_url} (с подписью)
7. Ваш сервер проверяет подпись, обновляет баланс пользователя
8. Пользователь перенаправляется на redirect_success_url
Выплата (Payout)
1. Пользователь запрашивает вывод на вашем сайте
2. Ваш сервер → POST /api/v1/orders/payouts (с подписью)
3. Kukuruku возвращает { uuid }
4. Kukuruku обрабатывает вывод
5. Kukuruku → POST {callback_url} (с подписью)
6. Ваш сервер проверяет подпись, подтверждает вывод
Обработка ошибок
| HTTP код | Описание |
|---|---|
200 | Успех |
400 | Некорректный запрос (отсутствуют поля, неверная сумма, пользователь не найден) |
401 | Неверная или отсутствующая подпись |
404 | Ордер не найден |
500 | Внутренняя ошибка сервера |
Все ответы об ошибках имеют формат:
{
"err": "описание ошибки"
}