Уведомления
Подписанные уведомления о платежах, возвратах и выплатах: адрес контура или адрес в запросе, секрет, проверка подписи, состав тела и порядок доставки.
Когда меняется платёж, возврат или выплата, на адрес мерчанта приходит уведомление: POST с телом JSON и подписью. Уведомление это повод прочитать объект, а не замена чтению: состояние в ответе чтения главнее.
Адрес и секрет
- Уведомления подписываются секретом контура вида
whsec_…: он один на контур и показывается один раз. Храните его на сервере, рядом с ключом API. - Адрес контура, если он нужен, один на контур. Его заводит администратор Paydex по вашей просьбе или вы сами в кабинете мерчанта: https с открытым в интернет именем узла и портом по умолчанию, 443, 8443, 80 или 8080, в тестовом контуре можно и http. Внутренние адреса не принимаются. Вместе с адресом выпускается и секрет.
- Адрес можно передавать и в каждом запросе: Адрес в запросе. Тогда адрес контура не обязателен, а секрет выпускается ключом API.
- После смены секрета прежний ещё сутки подписывает вместе с новым: в заголовке две подписи, и сверка проходит по любой. За эти сутки поменяйте секрет у себя.
Адрес в запросе
Как callback_url у Corefy: поле callbackUrl в теле POST /api/v1/payments, POST /api/v1/payments/:id/refunds и POST /api/v1/payouts. Уведомления об этом платеже, возврате или выплате уходят на него вместо адреса контура. Ответ создания и чтения отдаёт callbackUrl, в теле уведомления его нет.
- Требования те же, что к адресу контура: https до 2048 знаков, в тестовом контуре можно http; полное имя узла в интернете (не
localhost, не имя без точки, не.local,.internal,.lan,.localdomain,.home.arpa), порт по умолчанию, 443, 8443, 80 или 8080; без имени пользователя и пароля, без фрагмента. Иначе отказ 400 с правиломcallback_url_invalid,callback_url_schemeилиcallback_url_internal. - Имя узла проверяется при каждой доставке: если оно ведёт во внутреннюю, частную, петлевую или link-local сеть, уведомление не отправляется.
- Адрес задаётся при создании и потом не меняется: все уведомления объекта уходят на него.
- Подпись та же: секретом контура. Если у контура секрета нет, создание с
callbackUrlотказывает 409callback_secret_missing; у возврата и выплаты этот отказ занимает ключ повтора, повторяйте с новым ключом. - Адрес входит в тело запроса для ключа повтора: повтор тем же ключом с другим адресом получит 409
idempotency_key_reused, как с любым другим изменённым полем. - Если администратор выключил уведомления контура, по адресу в запросе они тоже не уходят, а создание проходит.
Секрет без администратора
Если адреса контура нет, секрет выпускают ключом API, один раз:
curl -X POST https://api.paydex.co.uk/notifications/secret -H "Authorization: Bearer $PAYDEX_API_KEY"Ответ 201 с полем secret приходит один раз. Повторный вызов отвечает 409 notify_secret_exists: секрет уже есть, повторно его не показывают. Потерянный секрет меняют в кабинете мерчанта (страница «Уведомления», с кодом из приложения) или у администратора; ключом API сменить его нельзя, чтобы утёкший ключ не давал подписывать уведомления. Ручка в справочнике: Выпустить секрет.
Подпись
Подпись устроена по спецификации Standard Webhooks, подходит и готовая библиотека для неё.
| Заголовок | Что в нём |
|---|---|
webhook-id | Номер события, тот же, что id в теле |
webhook-timestamp | Момент отправки этой попытки, секунды Unix |
webhook-signature | v1, и подпись в base64; при смене секрета две, через пробел |
Подпись это HMAC-SHA-256 строки <webhook-id>.<webhook-timestamp>.<тело>, где тело взято ровно так, как пришло, а ключ это base64 после whsec_. Отклоняйте запрос без подписи, с чужой подписью и с меткой времени старше пяти минут.
import { createHmac, timingSafeEqual } from 'node:crypto';
// secret: whsec_...; headers: request headers in lower case; body: the raw request body as received.
export function verifyWebhook(secret, headers, body, toleranceSeconds = 300, nowSeconds = Math.floor(Date.now() / 1000)) {
const id = headers['webhook-id'];
const timestamp = headers['webhook-timestamp'];
const signatures = headers['webhook-signature'];
if (!id || !timestamp || !signatures) return false;
const sent = Number(timestamp);
if (!Number.isInteger(sent) || Math.abs(nowSeconds - sent) > toleranceSeconds) return false;
const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
const expected = createHmac('sha256', key).update(`${id}.${timestamp}.${body}`).digest();
return signatures.split(' ').some((part) => {
const [version, value] = part.split(',');
if (version !== 'v1' || !value) return false;
const given = Buffer.from(value, 'base64');
return given.length === expected.length && timingSafeEqual(given, expected);
});
}События
payment.updated: изменилось одно из полей тела уведомления, например статус, причина, разбор или оплаченная сумма. Первое уведомление о платеже приходит примерно через минуту после создания, раньше, если платёж за это время изменился.refund.updated: возврат прошёл, не прошёл или ушёл в разбор.payout.updated: изменилось одно из полей тела уведомления, например статус, причина, решение модерации или разбор. Первое уведомление о выплате приходит примерно через минуту после создания, раньше, если выплата за это время изменилась (например, вы её отменили). Если адрес включили после создания выплаты, первое уведомление придёт при её перемене.
Тело payment.updated
| Поле | Вид | В ответе | Что это |
|---|---|---|---|
id | строка | всегда | Номер события. Тот же при каждом повторе доставки: по нему узнают повтор. |
type | строкаpayment.updated | всегда | Вид события: payment.updated. |
createdAt | строка | всегда | Когда событие записано, время UTC. |
sequence | целое число | всегда | Номер события этого объекта: растёт на единицу с каждым событием. Порядок доставки не гарантирован, сверяйте по нему. |
payment | объект | всегда | Платёж, как его отдаёт чтение, без action, pageUrl, customer, metadata, returnUrl, callbackUrl и refundedMinor. |
payment.id | строка | всегда | Номер платежа: pr_ и 22 знака. По нему платёж читают. |
payment.reference | строка | всегда | Номер заказа, присланный при создании. |
payment.service | строкаили null | всегда | Код сервиса, которым создан платёж. |
payment.environment | строкаTEST LIVE | всегда | Контур платежа: контур ключа, которым он создан. |
payment.status | строкаCREATED PROCESSING AWAITING_CUSTOMER SUCCEEDED PARTIALLY_PAID OVERPAID FAILED CANCELLED EXPIRED REJECTED | всегда | Статус платежа: Статусы платежа. |
payment.reason | строкаили null | всегда | Причина статуса кодом; null, когда называть нечего: Причины. |
payment.inReview | логическое | всегда | Исход ещё решается на нашей стороне: доспросом провайдера или человеком. Пока true, по платежу не зачисляют. |
payment.amountMinor | строка | всегда | Запрошенная сумма строкой, в минорных единицах валюты платежа. |
payment.currency | строка | всегда | Валюта платежа: валюта сервиса. |
payment.network | строкаили null | всегда | Сеть, если у валюты их несколько. null: сети нет. |
payment.paidMinor | строкаили null | всегда | Сумма, которую подтвердил провайдер, в минорных единицах валюты платежа. Зачисляют её и только при SUCCEEDED. null: денег не подтверждено. |
payment.feeMinor | строкаили null | всегда | Комиссия с мерчанта за платёж в минорных единицах валюты платежа, посчитанная при создании. |
payment.createdAt | строка | всегда | Когда платёж создан, время UTC. |
payment.expiresAt | строкаили null | всегда | Срок оплаты, время UTC: Срок оплаты. |
payment.finalizedAt | строкаили null | всегда | Когда платёж получил финальный статус, время UTC. null: ещё не получил. |
{
"id": "evt_8k3m2q7w9x4t6v5n2b8c4d_3",
"type": "payment.updated",
"createdAt": "2026-11-13T09:17:40.598Z",
"sequence": 3,
"payment": {
"id": "pr_8k3m2q7w9x4t6v5n2b8c4d",
"reference": "order-1001",
"service": "pix_brl_redirect",
"environment": "TEST",
"status": "SUCCEEDED",
"reason": null,
"inReview": false,
"amountMinor": "1250",
"currency": "BRL",
"network": null,
"paidMinor": "1250",
"feeMinor": "24",
"createdAt": "2026-11-13T09:15:02.481Z",
"expiresAt": "2026-11-13T09:45:02.481Z",
"finalizedAt": "2026-11-13T09:17:40.112Z"
}
}Тело refund.updated
| Поле | Вид | В ответе | Что это |
|---|---|---|---|
id | строка | всегда | Номер события. Тот же при каждом повторе доставки: по нему узнают повтор. |
type | строкаrefund.updated | всегда | Вид события: refund.updated. |
createdAt | строка | всегда | Когда событие записано, время UTC. |
sequence | целое число | всегда | Номер события этого объекта: растёт на единицу с каждым событием. Порядок доставки не гарантирован, сверяйте по нему. |
refund | объект | всегда | Возврат, как его отдаёт чтение, без description, metadata и callbackUrl. |
refund.id | строка | всегда | Номер возврата: rf_ и 22 знака. |
refund.payment | строка | всегда | Номер платежа, деньги которого возвращаются. |
refund.reference | строка | всегда | Номер возврата, присланный при создании. |
refund.environment | строкаTEST LIVE | всегда | Контур возврата: контур платежа. |
refund.status | строкаPENDING SUCCEEDED FAILED | всегда | PENDING возврат идёт или его исход неизвестен, SUCCEEDED деньги ушли, FAILED возврата не было. Незнакомый статус читайте как PENDING. |
refund.reason | строкаили nullrefund_declined technical_failure operator_declined | всегда | Причина неуспеха: refund_declined провайдер отказал, technical_failure технический сбой, operator_declined отказал сотрудник. У остальных статусов null. |
refund.inReview | логическое | всегда | Исход возврата под вопросом. У PENDING его называет доспрос провайдера или решение сотрудников, а если провайдер вернул другую сумму, исправление вручную; у FAILED и SUCCEEDED это поздний спорный ответ провайдера, и сам он не снимается. Пока true, тех же денег не возвращайте. |
refund.amountMinor | строка | всегда | Сумма возврата в минорных единицах валюты платежа. |
refund.currency | строка | всегда | Валюта возврата: валюта платежа. |
refund.feeMinor | строка | всегда | Комиссия за возврат в минорных единицах валюты платежа, сверх суммы возврата. |
refund.providerRefundId | строкаили null | всегда | Номер операции возврата у провайдера, если он его назвал: его называют в банке плательщика. |
refund.createdAt | строка | всегда | Когда возврат создан, время UTC. |
refund.finalizedAt | строкаили null | всегда | Когда возврат получил исход, время UTC. null: ещё не получил. |
{
"id": "evt_rf_5n7q2w8x4k3m9t6v2b8c4d_1",
"type": "refund.updated",
"createdAt": "2026-11-14T10:03:12.871Z",
"sequence": 1,
"refund": {
"id": "rf_5n7q2w8x4k3m9t6v2b8c4d",
"payment": "pr_8k3m2q7w9x4t6v5n2b8c4d",
"reference": "refund-1001-1",
"environment": "TEST",
"status": "SUCCEEDED",
"reason": null,
"inReview": false,
"amountMinor": "500",
"currency": "BRL",
"feeMinor": "0",
"providerRefundId": "RF-88213",
"createdAt": "2026-11-14T10:02:11.904Z",
"finalizedAt": "2026-11-14T10:03:12.550Z"
}
}Тело payout.updated
| Поле | Вид | В ответе | Что это |
|---|---|---|---|
id | строка | всегда | Номер события. Тот же при каждом повторе доставки: по нему узнают повтор. |
type | строкаpayout.updated | всегда | Вид события: payout.updated. |
createdAt | строка | всегда | Когда событие записано, время UTC. |
sequence | целое число | всегда | Номер события этого объекта: растёт на единицу с каждым событием. Порядок доставки не гарантирован, сверяйте по нему. |
payout | объект | всегда | Выплата, как её отдаёт чтение, без metadata и callbackUrl. |
payout.id | строка | всегда | Номер выплаты: po_ и 22 знака. По нему выплату читают и отменяют. |
payout.reference | строка | всегда | Номер вывода, присланный при создании. |
payout.service | строка | всегда | Код сервиса, которым заведена выплата. |
payout.environment | строкаTEST LIVE | всегда | Контур выплаты: контур ключа, которым она заведена. |
payout.status | строкаCREATED PROCESSING SUCCEEDED FAILED REJECTED CANCELLED | всегда | CREATED заведена и ждёт решения или отправки, PROCESSING отправлена, SUCCEEDED деньги ушли, FAILED не ушли, REJECTED отклонена, CANCELLED отменена до отправки. Незнакомый статус читайте как PROCESSING. |
payout.reason | строкаили nullcustomer_blocked rejected_by_operator cancelled_by_merchant | всегда | Причина закрытия: customer_blocked клиент или реквизит заблокирован, rejected_by_operator отклонил сотрудник, cancelled_by_merchant отменили вы. У остальных null. |
payout.approval | строкаPENDING APPROVED REJECTED WITHDRAWN | всегда | Решение модерации: APPROVED одобрена, PENDING ждёт сотрудника, REJECTED отклонена, WITHDRAWN снята вашей отменой. |
payout.inReview | логическое | всегда | Исход выплаты решается на нашей стороне. Пока true, не возвращайте игроку баланс и не считайте выплату прошедшей. |
payout.amountMinor | строка | всегда | Сколько получит игрок, в минорных единицах валюты выплаты. |
payout.currency | строка | всегда | Валюта выплаты: валюта сервиса. |
payout.feeMinor | строка | всегда | Комиссия за выплату в минорных единицах валюты выплаты, сверх суммы. |
payout.createdAt | строка | всегда | Когда выплата заведена, время UTC. |
payout.finalizedAt | строкаили null | всегда | Когда выплата закрылась, время UTC. null: ещё нет. |
{
"id": "evt_po_3m8q2w7k9x4t6v5n2b8c4d_2",
"type": "payout.updated",
"createdAt": "2026-11-17T09:43:52.041Z",
"sequence": 2,
"payout": {
"id": "po_3m8q2w7k9x4t6v5n2b8c4d",
"reference": "withdrawal-2001",
"service": "payout_pix_brl_direct",
"environment": "TEST",
"status": "CANCELLED",
"reason": "cancelled_by_merchant",
"approval": "APPROVED",
"inReview": false,
"amountMinor": "15000",
"currency": "BRL",
"feeMinor": "250",
"createdAt": "2026-11-17T09:41:07.312Z",
"finalizedAt": "2026-11-17T09:43:52.018Z"
}
}Доставка
- Доставленным считается ответ 2xx за 10 секунд, соединение должно установиться за 5. Перенаправления не выполняются.
- Уведомления одного мерчанта уходят по одному: пока идёт доставка на медленный адрес, его остальные уведомления ждут своей очереди.
- Иначе уведомление отправляется снова: через 5 секунд, дальше вдвое реже, но не реже раза в час. Всего 30 попыток, около 20 часов; после них доставка прекращается.
- Если у платежа, возврата или выплаты есть событие новее, старое уже не отправляется.
- Порядок доставки не гарантирован, повторы возможны. Повтор узнают по
id, порядок поsequence. - Журнал доставки видят сотрудники Paydex: если уведомления не доходят, назовите им номер платежа или выплаты.
Правила для кода мерчанта
- Проверьте подпись и метку времени до разбора тела.
- Сохраните событие у себя и ответьте 2xx; обработку делайте после ответа. После 2xx событие больше не придёт. На событие вида, который вы не обрабатываете, тоже отвечайте 2xx: иначе его будут слать 30 раз.
- Обрабатывайте событие так, чтобы повтор с тем же
idничего не менял, и пропускайте событие соsequenceменьше уже обработанного. - Перед зачислением прочитайте платёж: Когда зачислять. Перед возвратом баланса игроку прочитайте выплату: Статусы выплаты.
- Незавершённые и истёкшие платежи, незавершённые возвраты и выплаты дочитывайте и сами: недоставленное за 30 попыток не досылается, а пока адрес выключен, события не пишутся.