Подпись запросов

Все серверные API-запросы к Kukuruku должны включать HMAC-SHA512 подпись в HTTP-заголовках. Это обеспечивает подлинность и целостность запросов.

Учётные данные

Вы получите их после регистрации вашего проекта:

Учётные данные	Пример	Описание
secret_key	rmQXpjQyAtzS65oVhRLwY9s669UyDKJl	Секретный ключ для подписи HMAC
merchant_id	1	Идентификатор вашего мерчанта

Управляйте учётными данными в личном кабинете мерчанта.

Подпись запросов

Каждый запрос к API Kukuruku должен включать:

1. Поле merchant_id в теле запроса
2. Заголовок signature в HTTP-заголовках

Алгоритм

1. Сериализуйте тело запроса в JSON-строку
2. Вычислите HMAC-SHA512 от JSON-строки, используя ваш secret_key
3. Установите полученную hex-строку как значение заголовка signature

Пример на Node.js

const axios = require('axios');
const sha512 = require('js-sha512').sha512;

const SECRET_KEY = 'rmQXpjQyAtzS65oVhRLwY9s669UyDKJl';

const data = {
  merchant_id: "1",
  amount: 50000,
  currency: "RUB",
  callback_url: "https://your-site.com/callback",
  order_number: "order-123",
  redirect_success_url: "https://your-site.com/success",
  redirect_fail_url: "https://your-site.com/fail",
  customer: {
    client_id: "user@example.com"
  }
};

const signature = sha512.hmac(SECRET_KEY, JSON.stringify(data));

await axios({
  method: 'POST',
  url: 'https://api.kukuruku.win/api/v1/orders/payins',
  data,
  headers: {
    'Content-Type': 'application/json',
    signature
  }
});

Пример на Python

import hmac
import hashlib
import json
import requests

SECRET_KEY = 'rmQXpjQyAtzS65oVhRLwY9s669UyDKJl'

data = {
    "merchant_id": "1",
    "amount": 50000,
    "currency": "RUB",
    "callback_url": "https://your-site.com/callback",
    "order_number": "order-123",
    "redirect_success_url": "https://your-site.com/success",
    "redirect_fail_url": "https://your-site.com/fail",
    "customer": {
        "client_id": "user@example.com"
    }
}

body = json.dumps(data, separators=(',', ':'))
signature = hmac.new(
    SECRET_KEY.encode(), body.encode(), hashlib.sha512
).hexdigest()

response = requests.post(
    'https://api.kukuruku.win/api/v1/orders/payins',
    json=data,
    headers={'signature': signature}
)

Пример на PHP

$secretKey = 'rmQXpjQyAtzS65oVhRLwY9s669UyDKJl';

$data = [
    'merchant_id' => '1',
    'amount' => 50000,
    'currency' => 'RUB',
    'callback_url' => 'https://your-site.com/callback',
    'order_number' => 'order-123',
    'redirect_success_url' => 'https://your-site.com/success',
    'redirect_fail_url' => 'https://your-site.com/fail',
    'customer' => [
        'client_id' => 'user@example.com'
    ]
];

$body = json_encode($data);
$signature = hash_hmac('sha512', $body, $secretKey);

$ch = curl_init('https://api.kukuruku.win/api/v1/orders/payins');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $body,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'signature: ' . $signature,
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);

---

Проверка подписи

Запросы от Kukuruku к вашему серверу (callback'и, ответы статуса ордера) включают заголовок signature. Всегда проверяйте его для подтверждения подлинности запроса.

Алгоритм

1. Прочитайте тело запроса как строку
2. Вычислите HMAC-SHA512 от тела, используя ваш secret_key
3. Сравните результат с заголовком signature

Пример на Node.js

const sha512 = require('js-sha512').sha512;

function verifySignature(body, signatureHeader, secretKey) {
  const expected = sha512.hmac(secretKey, JSON.stringify(body));
  return expected === signatureHeader;
}

// В обработчике callback'а:
app.post('/callback', (req, res) => {
  if (!verifySignature(req.body, req.headers.signature, SECRET_KEY)) {
    return res.status(401).json({ success: false, err: 'Invalid signature' });
  }

  // Обработка callback'а...
  res.json({ success: true });
});

Пример на Python

import hmac
import hashlib

def verify_signature(body: bytes, signature_header: str, secret_key: str) -> bool:
    expected = hmac.new(
        secret_key.encode(), body, hashlib.sha512
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Пример на PHP

function verifySignature(string $body, string $signatureHeader, string $secretKey): bool {
    $expected = hash_hmac('sha512', $body, $secretKey);
    return hash_equals($expected, $signatureHeader);
}

Безопасность

Всегда используйте сравнение с постоянным временем (как hmac.compare_digest в Python или hash_equals в PHP) для предотвращения атак по времени.