GGWPAY docs

Авторизация и подпись #

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

Одинаковы для всех ручек /gw/v1/.... Повторять их в описании каждой ручки незачем.

ЗаголовокОбяз.Значение
AuthorizationдаBearer <public_key>:<secret>
Content-Typeдля POSTapplication/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}/claimp2p: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; права выбираются при выпуске ключа в кабинете.

Ключ может быть выпущен на конкретный магазин — тогда все заявки, созданные этим ключом, относятся к нему, вместе с его ставкой и его статистикой. Передавать магазин в запросе не нужно и нечем — «Магазины».

Подпись #

text
строка_для_подписи = МЕТОД + "\n" + ПУТЬ + "\n" + SHA256_HEX(ТЕЛО) + "\n" + МЕТКА_ВРЕМЕНИ
подпись            = base64(HMAC-SHA256(secret, строка_для_подписи))
ЧастьЧто подставить
МЕТОДВерхний регистр: POST, GET
ПУТЬПуть без домена и без query-строки: /gw/v1/collect
ТЕЛОСырые байты тела, ровно те, что уйдут по сети. Для GET — пустая строка
МЕТКА_ВРЕМЕНИТо же значение, что в X-GGWPay-Timestamp

Окно метки времени — ±5 минут от времени сервера. Вне окна — 401.

Сегодня подпись необязательна: запрос совсем без обоих заголовков проходит по одному Authorization. Запрос с одним заголовком из двух или с неверной подписью отклоняется с 401 в любом режиме. Требование подписи включается флагом на нашей стороне — подписывайте с первого дня.

Рабочий пример #

Вход:

text
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

Строка для подписи:

text
POST
/gw/v1/collect
b18bf599fac43ccc4360e30584fb0de280254e34e4b8fa5413bb9ff3e4186d57
2026-09-23T10:15:00Z

Результат: CsIyL1V3V9jUufCHd/QxoCpXB5EiQDVzitnCXWuarLk=

PHP #

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 #

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 адреса). См. «Уведомления».