GGWPAY docs

Уведомления (коллбек) #

POST на ваш HTTPS-адрес, когда статус заявки меняет платформа: реквизит выдан, заявка оплачена, закрыта по сроку или без исполнителя — и когда по спору заявка закрыта на фактическую сумму (тогда в событии original_amount_minor — исходная сумма). Отмена, которую вы сами сделали через POST /gw/v1/collect/{reference}/cancel, коллбек не шлёт — итог приходит в ответе на отмену. Адрес задаётся в кабинете мерчанта, раздел «Коллбек» — там же один раз показывается его signing_secret. Подписка на события не настраивается: набор фиксирован платформой.

Адрес общий для всех магазинов. Если магазинов несколько, у каждого может быть свой адрес со своим signing_secret — см. Магазины → Адрес коллбека магазина.

Событий два: collect.status_changed — приём, disburse.status_changed — итог выплаты. По выводам событий нет — следите опросом.

Выплата: disburse.status_changed #

Приходит один раз, на итог выплаты: fulfilled (выплачено), declined (отменена площадкой, причина в decline_reason), lapsed (исполнитель не нашёлся за срок, деньги вернулись на баланс). Промежуточных событий («взята», «на проверке») нет — всё это время выплата sending. Отмену, которую вы сделали сами, коллбек не дублирует: итог — в ответе на отмену.

Тот же адрес, те же заголовки и подпись, что у приёма; X-GGWPay-Event-Type: disburse.status_changed, data — снимок GET /gw/v1/disburse/{reference}. Фильтр статусов адреса (например, «только fulfilled») действует и на выплаты.

Заголовки #

ЗаголовокЗначение
Content-Typeapplication/json
X-GGWPay-Event-IdСтабильный id события. Одинаков во всех повторах — дедуплицируйте по нему
X-GGWPay-Event-Typecollect.status_changed
X-GGWPay-TimestampUnix-секунды этой попытки доставки
X-GGWPay-Signaturet=<unix>,v1=<base64>

Старые интеграции получают то же самое в заголовках X-AURUM-*; новые события приходят только с X-GGWPay-*.

Тело #

ПолеТипОписание
event_typestringДублирует X-GGWPay-Event-Type
occurred_atdatetimeКогда статус изменился у нас. Одинаков во всех повторах
dataobjectСнимок заявки в формате GET /gw/v1/collect/{reference}, включая requisite при awaiting_payment
text
POST /ваш/адрес HTTP/1.1
Content-Type: application/json
X-GGWPay-Timestamp: 1758542400
X-GGWPay-Signature: t=1758542400,v1=IMWQa8l5yDAFOiRN9Yqxl3iXoFUT1hGEcdK4AtkhKD4=
X-GGWPay-Event-Id: 3f2504e0-4f89-41d3-9a0c-0305e82c3301
X-GGWPay-Event-Type: collect.status_changed

{"event_type":"collect.status_changed","occurred_at":"2026-09-22T12:03:00Z","data":{"reference":"ord_collect_1","merchant_reference":"order-42","status":"fulfilled","amount_minor":1000000,"currency":"RUB","method":"C2C","created_at":"2026-09-22T12:00:00Z","updated_at":"2026-09-22T12:03:00Z","settled_at":"2026-09-22T12:03:00Z"}}

Событие отправляется только когда меняется публичный статус: внутренние перестановки, дающие тот же статус, событий не порождают.

По договорённости площадка может ограничить коллбеки на ваш адрес отдельными статусами — например, только fulfilled. Тогда об остальных исходах (declined, lapsed, disputed, reversed) коллбек не придёт: узнавайте их через GET /gw/v1/collect/{reference}.

Доставка #

СвойствоЗначение
Попыток6: сразу, затем +1 мин, +5 мин, +15 мин, +1 ч, +6 ч
Таймаут попытки10 секунд
УспехЛюбой 2xx
Исчерпаны попыткиСобытие помечается недоставленным, разбор вручную
РедиректыНе следуем: 301/302 — это неуспех
Схема адресаТолько https://, без логина в URL, не на внутренние адреса — проверяется перед каждой доставкой
Мёртвый адресПосле 20 подряд неуспешных доставок адрес отключается; включается обратно в кабинете
Нет адресаСобытие ждёт появления адреса до суток, повторяя проверку каждые 5 минут

⚠️ Отсеивайте повторы и применяйте события по времени #

Доставка — хотя бы один раз и без гарантии порядка.

  1. Дедуп по X-GGWPay-Event-Id. Он одинаков во всех повторах. Сохраняйте обработанные id и игнорируйте уже виденные. Иначе повтор начислит платёж дважды — в том числе когда вы ответили 2xx, а мы его не получили.
  2. Применяйте по occurred_at, а не по порядку получения. Событие старше уже применённого по той же заявке — отбросьте молча.

occurred_at (тело) и t= (заголовок подписи) — разные вещи: t= меняется на каждой попытке доставки. Для дедупа и упорядочивания — occurred_at.


Проверка подписи #

Путь в подпись не входит — вы вольны повесить обработчик куда угодно. Секрет — signing_secret адреса, не secret API-ключа.

Секрет — это 64 шестнадцатеричных символа, и перед подписью их надо декодировать в 32 байта. Ключом HMAC служат байты, а не та строка, которую вы скопировали из кабинета. Подпишете строкой — не сойдётся ни одна доставка, и выглядеть это будет как «у вас сломана подпись».

text
ключ          = hex_decode(signing_secret)   // 64 символа → 32 байта
подписываемое = t + "." + сырое_тело
подпись       = base64(HMAC-SHA256(ключ, подписываемое))

Считайте по сырым байтам тела, до разбора JSON. Сравнивайте постоянным по времени сравнением (hash_equals, hmac.compare_digest). Проверяйте t= на окно в несколько минут по своим часам — реплей-защиту включаете вы, платформа за вас этого не сделает.

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

text
signing_secret = 5f3c8d1a9b7e4a2c8f6d0b3e7a1c9d5f2b8e4a7c1d6f0b3e9a5c8d2f7b1e4a6c
t              = 1758542400
body           = {"event_type":"collect.status_changed","occurred_at":"2026-09-22T12:03:00Z","data":{"reference":"ord_collect_1","merchant_reference":"order-42","status":"fulfilled","amount_minor":1000000,"currency":"RUB"}}

Ожидаемое v1: elkjaEXNwQOmoThx3KAw6jLUibJMHo115XaItpSfWBg=

Если получилось ogal1BKLhMILK8QJ/LG1xewIIG3+fYNJxoPg/gY9/oo= — секрет не декодирован из hex.

PHP #

php
<?php

function verifyGgwpayCallback(string $secret, string $header, string $rawBody): bool
{
    $parts = [];
    foreach (explode(',', $header) as $kv) {
        [$k, $v] = array_pad(explode('=', $kv, 2), 2, null);
        $parts[$k] = $v;
    }
    if (!isset($parts['t'], $parts['v1']) || abs(time() - (int) $parts['t']) > 300) {
        return false;
    }
    $key = hex2bin($secret);            // 64 символа → 32 байта
    $expected = base64_encode(hash_hmac('sha256', $parts['t'] . '.' . $rawBody, $key, true));
    return hash_equals($expected, $parts['v1']);
}
// $rawBody = file_get_contents('php://input'); — ДО json_decode

Python #

python
def verify_ggwpay_callback(secret: str, header: str, raw_body: bytes, max_skew: int = 300) -> bool:
    parts = dict(kv.split("=", 1) for kv in header.split(","))
    ts, v1 = parts.get("t"), parts.get("v1")
    if ts is None or v1 is None or abs(time.time() - int(ts)) > max_skew:
        return False
    key = bytes.fromhex(secret)  # 64 символа → 32 байта
    mac = hmac.new(key, f"{ts}.".encode() + raw_body, hashlib.sha256)
    return hmac.compare_digest(base64.b64encode(mac.digest()).decode(), v1)

Ответ #

Верните 2xx сразу, как сохранили событие, — не после всей бизнес-логики. Долгую обработку уносите в свою очередь. Любой не-2xx, таймаут или разрыв — неуспех и повтор по расписанию выше.