Возврат и уведомление — две разные операции. Если деньги уже подтверждены платёжным провайдером, не нажимайте «вернуть» повторно: найдите refund ID, затем отдельно проверьте outbox, задачу отправки и событие email-провайдера. Повторять можно письмо, но не финансовую команду.

Надёжная схема создаёт запись уведомления при переходе refund в финальный статус и присваивает ей собственный ключ, например `refund_succeeded:{refund_id}:{locale}`. Это позволяет безопасно перезапустить worker и увидеть, на каком участке исчезло сообщение.

Четыре статуса вместо одного флага sent

СлойКонтрольный идентификаторЧто подтверждает
Платёжный провайдерrefund IDФактический status и сумма возврата
Transactional outboxnotification keyСобытие зафиксировано вместе с локальным статусом
Email APIprovider message IDПровайдер принял запрос на отправку
Delivery eventmessage ID + recipientСервер получателя принял письмо либо вернул bounce
Клиентский интерфейсrefund IDПользователь видит актуальное состояние независимо от email

Ответ `200` от email API обычно означает приём задачи, а не появление письма во входящих. Amazon SES, например, публикует отдельные delivery, bounce, complaint и delivery-delay events. Сохраните их рядом с message ID, чтобы оператор не угадывал результат по одному полю.

Outbox появляется в транзакции со статусом

BEGIN
  UPDATE refunds SET status = confirmed WHERE id = :refund_id
  INSERT INTO notification_outbox(
    key, type, aggregate_id, state
  ) VALUES (
    refund_succeeded:{refund_id}:ru, refund_succeeded, :refund_id, pending
  ) ON CONFLICT (key) DO NOTHING
COMMIT

Worker берёт pending-запись, загружает шаблон и контакт из актуального разрешённого источника, отправляет письмо и сохраняет provider message ID. Если процесс упал после запроса, повтор сначала проверяет сохранённый результат или использует стабильный idempotency key там, где API это поддерживает.

Причина находится по последней успешной точке

  • Нет outbox — переход refund не вызвал доменное событие или транзакция откатилась.
  • Outbox pending — worker остановлен, завис lease или исчерпаны попытки.
  • Email API rejected — адрес, шаблон, sandbox или политика провайдера не прошли проверку.
  • Provider accepted без delivery — ждите итоговый event и смотрите delivery delay.
  • Delivery есть, клиент не видит письмо — проверьте spam, threading и неверный адрес в snapshot.

Не помещайте полный email и содержимое письма в общий технический лог. Для поиска достаточно hash/внутреннего contact ID, provider message ID, template version, locale и кода результата. Доступ к расшифровке адреса должен быть отдельным.

Повторная отправка не переписывает историю

Кнопка оператора создаёт новую delivery attempt для существующего notification key. Она не меняет время возврата и не маскирует первый bounce. В интерфейсе полезно показать «возврат подтверждён» и отдельно «письмо: ошибка адреса / доставлено / ожидает».

Если адрес исправили, сохраните новый recipient snapshot только для новой попытки и запишите, кто её запустил. Старое сообщение остаётся в аудите без повторного включения персональных данных в текст события.

Приёмка включает недоставляемый адрес

В тесте проведите успешный refund, повтор того же webhook, временную ошибку email API и hard bounce. Должен существовать один возврат, одно логическое уведомление и несколько нумерованных попыток доставки. Личный кабинет показывает финансовый результат даже при постоянной ошибке почты.

Для разбора подготовьте обезличенные refund status transitions, outbox key, message ID, коды delivery events и версию шаблона. API-ключи, подписи webhook и реальный адрес клиента передавать не нужно.

Проверенные источники