Уведомления (коллбек) #
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-Type | application/json |
X-GGWPay-Event-Id | Стабильный id события. Одинаков во всех повторах — дедуплицируйте по нему |
X-GGWPay-Event-Type | collect.status_changed |
X-GGWPay-Timestamp | Unix-секунды этой попытки доставки |
X-GGWPay-Signature | t=<unix>,v1=<base64> |
Старые интеграции получают то же самое в заголовках X-AURUM-*; новые события приходят только с X-GGWPay-*.
Тело #
| Поле | Тип | Описание |
|---|---|---|
event_type | string | Дублирует X-GGWPay-Event-Type |
occurred_at | datetime | Когда статус изменился у нас. Одинаков во всех повторах |
data | object | Снимок заявки в формате GET /gw/v1/collect/{reference}, включая requisite при awaiting_payment |
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 минут |
⚠️ Отсеивайте повторы и применяйте события по времени #
Доставка — хотя бы один раз и без гарантии порядка.
- Дедуп по
X-GGWPay-Event-Id. Он одинаков во всех повторах. Сохраняйте обработанные id и игнорируйте уже виденные. Иначе повтор начислит платёж дважды — в том числе когда вы ответили2xx, а мы его не получили.- Применяйте по
occurred_at, а не по порядку получения. Событие старше уже применённого по той же заявке — отбросьте молча.
occurred_at(тело) иt=(заголовок подписи) — разные вещи:t=меняется на каждой попытке доставки. Для дедупа и упорядочивания —occurred_at.
Проверка подписи #
Путь в подпись не входит — вы вольны повесить обработчик куда угодно. Секрет — signing_secret адреса, не secret API-ключа.
Секрет — это 64 шестнадцатеричных символа, и перед подписью их надо декодировать в 32 байта. Ключом HMAC служат байты, а не та строка, которую вы скопировали из кабинета. Подпишете строкой — не сойдётся ни одна доставка, и выглядеть это будет как «у вас сломана подпись».
ключ = hex_decode(signing_secret) // 64 символа → 32 байта
подписываемое = t + "." + сырое_тело
подпись = base64(HMAC-SHA256(ключ, подписываемое))Считайте по сырым байтам тела, до разбора JSON. Сравнивайте постоянным по времени сравнением (hash_equals, hmac.compare_digest). Проверяйте t= на окно в несколько минут по своим часам — реплей-защиту включаете вы, платформа за вас этого не сделает.
Рабочий пример #
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
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_decodePython #
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, таймаут или разрыв — неуспех и повтор по расписанию выше.