Авторизация и подпись #
Заголовки запроса #
Одинаковы для всех ручек /gw/v1/.... Повторять их в описании каждой ручки незачем.
| Заголовок | Обяз. | Значение |
|---|---|---|
Authorization | да | Bearer <public_key>:<secret> |
Content-Type | для POST | application/json |
X-GGWPay-Timestamp | см. ниже | Метка времени RFC3339 UTC: 2026-09-23T10:15:00Z |
X-GGWPay-Signature | см. ниже | base64(HMAC-SHA256(secret, строка_для_подписи)) |
X-Request-Id | нет | Ваш идентификатор запроса. Возвращается в заголовке ответа и в error.request_id |
X-Trace-Id | нет | Ваш идентификатор трассировки, доезжает до наших логов событий |
Песочница (/sandbox/v1/...) не требует ни одного из них — там нечего проверять.
Ключ #
public_key начинается с ak_, не секретен. secret показывается один раз при выпуске, хранится у нас только необратимым хешем — потерянный секрет не восстанавливается, выпускается новый ключ.
Ключ несёт права (scopes): p2p:payin — создавать приём, p2p:payout — создавать выплату. Ключ без нужного права получает 403.
Право проверяется на каждой ручке:
| Ручка | Нужное право |
|---|---|
POST /gw/v1/collect, POST /gw/v1/collect/{reference}/cancel, POST и DELETE /gw/v1/collect/{reference}/claim | p2p:payin |
POST /gw/v1/disburse, POST /gw/v1/settlement (вывод на белый список) | p2p:payout |
Чтение: GET заявки, выплаты и вывода, /account, /account/movements, /catalog/banks, /rates/{currency} | любое из двух |
Ключ «только приём» (p2p:payin) не создаёт вывод (settlement): нужен ключ с p2p:payout. Ключ без единого права не пускается никуда и получает 403; права выбираются при выпуске ключа в кабинете.
Ключ может быть выпущен на конкретный магазин — тогда все заявки, созданные этим ключом, относятся к нему, вместе с его ставкой и его статистикой. Передавать магазин в запросе не нужно и нечем — «Магазины».
Подпись #
строка_для_подписи = МЕТОД + "\n" + ПУТЬ + "\n" + SHA256_HEX(ТЕЛО) + "\n" + МЕТКА_ВРЕМЕНИ
подпись = base64(HMAC-SHA256(secret, строка_для_подписи))| Часть | Что подставить |
|---|---|
МЕТОД | Верхний регистр: POST, GET |
ПУТЬ | Путь без домена и без query-строки: /gw/v1/collect |
ТЕЛО | Сырые байты тела, ровно те, что уйдут по сети. Для GET — пустая строка |
МЕТКА_ВРЕМЕНИ | То же значение, что в X-GGWPay-Timestamp |
Окно метки времени — ±5 минут от времени сервера. Вне окна — 401.
Сегодня подпись необязательна: запрос совсем без обоих заголовков проходит по одному Authorization. Запрос с одним заголовком из двух или с неверной подписью отклоняется с 401 в любом режиме. Требование подписи включается флагом на нашей стороне — подписывайте с первого дня.
Рабочий пример #
Вход:
secret = sk_live_example_secret_change_me
method = POST
path = /gw/v1/collect
body = {"amount_minor":1000000,"currency":"RUB","method":"C2C","merchant_reference":"order-42"}
timestamp = 2026-09-23T10:15:00ZСтрока для подписи:
POST
/gw/v1/collect
b18bf599fac43ccc4360e30584fb0de280254e34e4b8fa5413bb9ff3e4186d57
2026-09-23T10:15:00ZРезультат: CsIyL1V3V9jUufCHd/QxoCpXB5EiQDVzitnCXWuarLk=
PHP #
function ggwpaySign(string $secret, string $method, string $path, string $body, string $timestamp): string
{
$stringToSign = implode("\n", [strtoupper($method), $path, hash('sha256', $body), $timestamp]);
return base64_encode(hash_hmac('sha256', $stringToSign, $secret, true));
}Python #
def ggwpay_sign(secret: str, method: str, path: str, body: bytes, timestamp: str) -> str:
string_to_sign = "\n".join([method.upper(), path, hashlib.sha256(body).hexdigest(), timestamp])
mac = hmac.new(secret.encode(), string_to_sign.encode(), hashlib.sha256)
return base64.b64encode(mac.digest()).decode()Частые ошибки #
- Тело пересобрано после подписи (порядок ключей, пробелы) — подписывайте те же байты, что уйдут в сеть.
- В путь попала query-строка.
- Метка времени в локальном времени, а не UTC с суффиксом
Z. - Подпись закодирована в
hexилиbase64urlвместоbase64.
Подпись коллбека — другая #
В подпись входящего от нас уведомления не входит путь, и секрет там другой (signing_secret адреса). См. «Уведомления».