Уведомления

Подписанные уведомления о платежах, возвратах и выплатах: адрес контура или адрес в запросе, секрет, проверка подписи, состав тела и порядок доставки.

Когда меняется платёж, возврат или выплата, на адрес мерчанта приходит уведомление: POST с телом JSON и подписью. Уведомление это повод прочитать объект, а не замена чтению: состояние в ответе чтения главнее.

Адрес и секрет

  • Уведомления подписываются секретом контура вида whsec_…: он один на контур и показывается один раз. Храните его на сервере, рядом с ключом API.
  • Адрес контура, если он нужен, один на контур. Его заводит администратор Target по вашей просьбе или вы сами в кабинете мерчанта: 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 отказывает 409 callback_secret_missing; у возврата и выплаты этот отказ занимает ключ повтора, повторяйте с новым ключом.
  • Адрес входит в тело запроса для ключа повтора: повтор тем же ключом с другим адресом получит 409 idempotency_key_reused, как с любым другим изменённым полем.
  • Если администратор выключил уведомления контура, по адресу в запросе они тоже не уходят, а создание проходит.

Секрет без администратора

Если адреса контура нет, секрет выпускают ключом API, один раз:

curl -X POST https://api.thetarget.cc/notifications/secret -H "Authorization: Bearer $TARGET_API_KEY"

Ответ 201 с полем secret приходит один раз. Повторный вызов отвечает 409 notify_secret_exists: секрет уже есть, повторно его не показывают. Потерянный секрет меняют в кабинете мерчанта (страница «Уведомления», с кодом из приложения) или у администратора; ключом API сменить его нельзя, чтобы утёкший ключ не давал подписывать уведомления. Ручка в справочнике: Выпустить секрет.

Подпись

Подпись устроена по спецификации Standard Webhooks, подходит и готовая библиотека для неё.

ЗаголовокЧто в нём
webhook-idНомер события, тот же, что id в теле
webhook-timestampМомент отправки этой попытки, секунды Unix
webhook-signaturev1, и подпись в base64; при смене секрета две, через пробел

Подпись это HMAC-SHA-256 строки <webhook-id>.<webhook-timestamp>.<тело>, где тело взято ровно так, как пришло, а ключ это base64 после whsec_. Отклоняйте запрос без подписи, с чужой подписью и с меткой времени старше пяти минут.

verify-webhook.mjs
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.
  • Журнал доставки видят сотрудники Target: если уведомления не доходят, назовите им номер платежа или выплаты.

Правила для кода мерчанта

  1. Проверьте подпись и метку времени до разбора тела.
  2. Сохраните событие у себя и ответьте 2xx; обработку делайте после ответа. После 2xx событие больше не придёт. На событие вида, который вы не обрабатываете, тоже отвечайте 2xx: иначе его будут слать 30 раз.
  3. Обрабатывайте событие так, чтобы повтор с тем же id ничего не менял, и пропускайте событие со sequence меньше уже обработанного.
  4. Перед зачислением прочитайте платёж: Когда зачислять. Перед возвратом баланса игроку прочитайте выплату: Статусы выплаты.
  5. Незавершённые и истёкшие платежи, незавершённые возвраты и выплаты дочитывайте и сами: недоставленное за 30 попыток не досылается, а пока адрес выключен, события не пишутся.

API v1 · собрано 18.11.2026 · выпуск f13e6bf

Справочник методов собирается из кода сервера: он не описывает адрес, которого нет.