Документация API

1. Общее описание сервиса

API платёжного сервиса предоставляет унифицированный интерфейс для инициализации, проведения и отслеживания платежей за цифровые товары и услуги (игры, подписки и т. д.).

Основные возможности:

• инициализация платежа с указанием товара и данных пользователя;

• запуск процесса оплаты;

• получение статуса платежа;

• просмотр списка доступных товаров/услуг;

• получение схемы полей для конкретной услуги.

Формат данных: JSON

Тип контента: application/json

2. Авторизация и безопасность

Для обеспечения безопасности запросов к API используется комбинация Basic Auth для идентификации партнёра и цифровой подписи в теле запроса для подтверждения целостности данных.

Механизм авторизации

1. Basic Auth: стандартная HTTP‑авторизация для идентификации партнёра.

2. Подпись в теле: параметр signature содержит HMAC‑подпись от тела запроса (без самого поля signature).

Обязательные компоненты:

• Заголовки: Authorization (Basic Auth).

• Тело запроса: поле signature с подписью.

Алгоритм создания подписи

1. Подготовьте тело запроса без поля signature.

2. Отсортируйте все поля JSON‑объекта по ключу в алфавитном порядке (для детерминированности).

3. Сериализуйте объект в строку без пробелов.

4. Создайте подпись:
   • используйте алгоритм HMAC‑SHA256;
   • в качестве ключа — секретный ключ партнёра;
   • входными данными — строка из шага 3.

5. Результат преобразуйте в hex‑формат (строчные буквы).

6. Добавьте поле "signature": "<результат>" в тело запроса.

Пример запросов

Инициализация платежа:

curl --location 'host/api/v1/payments/init' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic cGFydG5lcjEyMzQ2OnlvdXJzZWNyZXRfa2V5' \
--data '{
  "serviceId": "free_fire",
  "partnerTransactionId": "422443242333555",
  "extra": {
    "account": "any@gmail.com"
  },
  "signature": "a1b2c3d4e5f67890abcdef12345678001234567890abcdef1234567890abcde"
}'

3. Список доступных методов

4. Подробное описание методов

3.1. Инициализация платежа (POST /payments/init)

Создаёт новую платёжную операцию с предварительным резервированием суммы.

Запрос:

curl --location 'host/api/v1/payments/init' \
--header 'Content-Type: application/json' \
--data-raw '{
  "serviceId": "free_fire",
  "partnerTransactionId": "432443242333555",
  "extra": {
    "account": "any@gmail.com"
  }
}'

Входные параметры:

Ответ (успех, 200 OK):

{
  "id": "650e6fc9-2101-408c-9b39-ccc85a2387cb",
  "currency": "RUB",
  "amount": 499.7047,
  "status": "NEW",
  "itemCode": "free_fire",
  "partnerId": "8761b70f-1adc-420f-aa27-ee402f985752",
  "partnerPaymentId": "432443242333555",
  "createDate": "2026-03-23T13:18:56.709252",
  "payload": {
      "account":"any@gmail.com"
      }
}

4.2. Запуск процесса оплаты (POST /payments/pay)

Запускает процесс оплаты для предварительно инициализированного платежа.

curl --location 'host/api/v1/payments/pay' \
--header 'Content-Type: application/json' \
--data '{
  "paymentId": "650e6fc9-2101-408c-9b39-ccc85a2387cb"
}'

Входные параметры:

4.3. Получение статуса платежа (GET /payments/{paymentId})

Возвращает актуальную информацию о платеже, включая его статус.

curl --location --request GET 'host/api/v1/payments/650e6fc9-2101-408c-9b39-ccc85a2387cb' \
--header 'Content-Type: application/json'

4.4. Получение списка услуг (GET /items)

Возвращает список всех доступных для оплаты товаров и услуг.

curl --location 'host/api/v1/items' \
--data ''

4.5. Получение схемы полей для услуги (GET /items/{itemCode}/fields)

Возвращает структуру параметров, необходимых для инициализации платежа по конкретной услуге.

curl --location 'host/api/v1/items/discord_nitro/fields' \
--data ''

5. Коды ошибок и обработка исключений

• 200 OK — успешный запрос;
• 400 Bad Request — некорректные входные данные;
• 404 Not Found — ресурс не найден;
• 500 Internal Server Error — внутренняя ошибка сервера.

6. Примечания и рекомендации

1. Порядок работы с API: получить услуги → схему полей → инициализация → запуск оплаты → проверка статуса.
2. Валидация данных: обязательно передавать required поля.
3. Уникальность транзакций: partnerTransactionId должен быть уникальным.
4. Безопасность: все запросы по HTTPS.