Баланс начислений по приёму платежей

GET /api/v1/balance · HMAC как у остального merchant API

Эндпоинт показывает, сколько средств уже начислено мерчанту по успешным платежам на выбранных шлюзах — то, что внутри системы учитывается как «collect» (накопление после приёма оплат через выданные реквизиты). Это не баланс кошелька для вывода USDT и не сумма по счёту банка: только учётная величина начислений по вашим шлюзам.

В ответе два представления одной и той же суммы: в поле collectBalanceUsdt — всегда итог в USDT (основа учёта). Поля currency и totalCollectBalance — «удобная» строка для интерфейса: если по всем шлюзам получилась одна оценка в фиате (например только ₽), там будет сумма в этой валюте; если валют несколько или курс недоступен — показывают ту же сумму в USDT.

Если API-ключ привязан к одной шлюзе — считается только она. Если ключ общий — суммируются все шлюзы этого аккаунта мерчанта.

GET https://api.protopays.io/api/v1/balance

Заголовки запроса

Поле	Тип	Обяз.	Описание
Accept	string	нет	Рекомендуется application/json.
X-Merchant-Key-Id	string	да	Публичный key_id строки API-ключа.
Signature	string (hex)	да	HMAC-SHA256 от пустой строки (тело GET отсутствует), ключ — сырой секрет ключа; результат в нижнем hex.

Общая схема HMAC: см. аутентификация и создание платежа для POST (подпись там считается от JSON-тела; здесь — от пустой строки).

Примеры

curl

curl -sS -X GET 'https://api.protopays.io/api/v1/balance' \
  -H 'Accept: application/json' \
  -H 'X-Merchant-Key-Id: <KEY_ID>' \
  -H 'Signature: <SIGNATURE>'

Замените <SIGNATURE>: посчитайте HMAC-SHA256 от пустого тела тем же секретом, что для POST (например в PHP: hash_hmac("sha256", "", $secret)).

PHP

<?php
$base = rtrim('<BASE_URL>', '/');
$keyId = '<KEY_ID>';
$secret = '<SECRET>'; // сырой секрет из кабинета — только для HMAC

$canonicalBody = ''; // GET без тела
$signature = hash_hmac('sha256', $canonicalBody, $secret);

$ch = curl_init("{$base}/api/v1/balance");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'X-Merchant-Key-Id: ' . $keyId,
        'Signature: ' . $signature,
    ],
]);
echo curl_exec($ch);

Ответ

200 OK. В data ровно три поля.

Поле	Тип	Обяз.	Описание
currency	string	да	В какой валюте прочитан totalCollectBalance: например RUB при одной фиатной оценке по шлюзам; иначе USDT.
totalCollectBalance	string	да	Итог начислений для показа: в фиате (до 2 знаков) или в USDT (до 8 знаков) — см. currency.
collectBalanceUsdt	string	да	Тот же итог начислений, всегда выраженный в USDT — основное число для учёта.

{
  "data": {
    "currency": "RUB",
    "totalCollectBalance": "7107.69",
    "collectBalanceUsdt": "309.03010033"
  }
}