Аутентификация

HMAC-SHA256 аутентификация в API v2

Обзор

API v2 использует HMAC-SHA256 подпись для аутентификации всех запросов. Это обеспечивает:

• Подтверждение подлинности запроса
• Защиту от replay-атак
• Целостность передаваемых данных

Обязательные заголовки

Заголовок	Тип	Описание
x-api-key	string	Ваш API ключ (начинается с pk_live_ или pk_test_)
x-timestamp	string	Unix timestamp в миллисекундах
x-signature	string	HMAC-SHA256 подпись в hex формате

Важно! Timestamp должен быть в миллисекундах (13 цифр), а не в секундах. Запросы с timestamp старше 5 минут будут отклонены.

Алгоритм генерации подписи

signature = HMAC-SHA256(secretKey, METHOD + PATH + TIMESTAMP + SHA256(BODY))

Пошаговый процесс

1. Вычислите SHA256 хеш тела запроса

   Для GET запросов используйте пустую строку

2. Сформируйте строку для подписи

   Конкатенация: METHOD + PATH + TIMESTAMP + BODY_HASH

3. Подпишите строку

   HMAC-SHA256 используя ваш секретный ключ

4. Передайте в заголовке

   Результат в hex формате в x-signature

PATH в подписи не включает query параметры! Правильно: /api/v2/invoices Неправильно: /api/v2/invoices?limit=10

Примеры кода

JavaScript

const crypto = require('crypto');

const API_KEY = 'pk_live_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';
const SECRET_KEY = 'sk_live_your_secret_key_here';

function generateSignature(secretKey, method, path, timestamp, body = '') {
  // 1. Вычислить SHA256 хеш тела
  const bodyHash = crypto.createHash('sha256').update(body).digest('hex');

  // 2. Сформировать строку для подписи
  const message = `${method.toUpperCase()}${path}${timestamp}${bodyHash}`;

  // 3. Подписать HMAC-SHA256
  return crypto.createHmac('sha256', secretKey).update(message).digest('hex');
}

// Пример: создание счёта
async function createInvoice() {
  const timestamp = Date.now().toString();
  const method = 'POST';
  const path = '/api/v2/invoices';
  const body = JSON.stringify({
    amount: 1500.50,
    description: 'Оплата заказа #12345'
  });

  const signature = generateSignature(SECRET_KEY, method, path, timestamp, body);

  const response = await fetch('https://loveandpay.io' + path, {
    method: method,
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': API_KEY,
      'x-timestamp': timestamp,
      'x-signature': signature
    },
    body: body
  });

  return response.json();
}

// Пример: получение списка счетов (GET запрос)
async function getInvoices() {
  const timestamp = Date.now().toString();
  const method = 'GET';
  const path = '/api/v2/invoices'; // Без query параметров!

  const signature = generateSignature(SECRET_KEY, method, path, timestamp, '');

  const response = await fetch('https://loveandpay.io' + path + '?limit=50', {
    method: method,
    headers: {
      'x-api-key': API_KEY,
      'x-timestamp': timestamp,
      'x-signature': signature
    }
  });

  return response.json();
}

Получение ключей

1. Войдите в кабинет

   Панель управления → Профиль

2. API Key (публичный)

   Раздел «API Ключ (PERMANENT)» — постоянный ключ-идентификатор партнёра. Скопируйте его (UUID v4). Кнопка «Сгенерировать новый» заменит ключ — все интеграции на старом ключе перестанут работать сразу.

3. Secret Key (для v2)

   Раздел «API v2 — HMAC секретный ключ» → «Сгенерировать секретный ключ».

   Секрет показывается только один раз при создании. Сохраните его в менеджер паролей / переменные окружения сразу — потом увидеть его снова нельзя, можно только сгенерировать новый.

Храните секретный ключ в безопасности!

• Никогда не передавайте его на клиентскую сторону (браузер, мобильное приложение)
• Используйте переменные окружения, не хардкод в коде
• Не коммитьте в git
• В случае компрометации — немедленно сгенерируйте новый

Окружения

Сейчас все ключи — production. Тестовый sandbox в работе.

Для безопасной разработки рекомендуем:

• Использовать отдельный тестовый партнёрский аккаунт (свяжитесь с поддержкой для создания)
• Делать счета на минимальные суммы (от 10 ₽)
• После теста — отменить созданные счета через UI

Частые ошибки

INVALID_SIGNATURE

{
  "success": false,
  "error": {
    "code": "INVALID_SIGNATURE",
    "message": "Неверная HMAC подпись"
  }
}

Возможные причины:

• Неправильный порядок элементов в строке подписи
• Query параметры включены в PATH
• Неправильный формат body (пробелы, порядок ключей)
• Неверный секретный ключ

TIMESTAMP_EXPIRED

{
  "success": false,
  "error": {
    "code": "TIMESTAMP_EXPIRED",
    "message": "Timestamp устарел (более 5 минут)"
  }
}

Решение: Убедитесь, что время на сервере синхронизировано (NTP).

MISSING_HEADERS

{
  "success": false,
  "error": {
    "code": "MISSING_HEADERS",
    "message": "Отсутствует обязательный заголовок"
  }
}

Решение: Проверьте наличие всех трёх заголовков: x-api-key, x-timestamp, x-signature.