Промежуточный статус возврата нельзя исправлять повторным нажатием кнопки. Сначала запросите у платёжного провайдера тот же refund по его идентификатору, сравните ответ с журналом webhook и только затем синхронизируйте локальную запись. Новый refund допустим лишь после подтверждения, что прежняя операция не была создана.

У зависания обычно две разные причины: провайдер действительно ещё ждёт завершения операции либо финальное событие не дошло до приложения. В Stripe объект Refund может иметь состояния `pending`, `requires_action`, `succeeded`, `failed` и `canceled`. Эти значения нужно отобразить на собственную машину состояний, не превращая сетевой timeout в финансовый результат.

Сначала соберите одну временную линию

ИсточникЧто выписатьЧто доказывает
Локальная базаrefund ID, payment ID, сумма, валюта, created_at, updated_atКакое состояние видит продукт
Ответ create refundHTTP status, provider refund ID, status, request IDПринял ли провайдер запрос
API провайдера сейчасТекущий status и failure reasonФактическое состояние на момент сверки
Webhook endpointevent ID, type, created time, delivery attemptsБыло ли финальное событие доставлено
Очередь обработчикаattempt, ошибка, dead-letter statusНе потерялось ли событие после приёма

Все отметки времени приведите к одной временной зоне. Ищите не по имени клиента, а по внутреннему refund ID, provider ID и request ID. В выгрузку для поддержки не включайте номер карты, секретный ключ и полный payload с персональными данными.

Проверка начинается с существующего refund

Если create-запрос вернул timeout, результат неизвестен: HTTP-клиент мог потерять ответ после того, как провайдер создал возврат. Повтор с новым idempotency key способен создать вторую операцию. Сначала найдите прежний объект по сохранённому provider ID, idempotency key, metadata или списку refunds исходного платежа.

refund = provider.get_refund(provider_refund_id)

switch refund.status:
  case 'succeeded': mark_succeeded_once(refund.id)
  case 'failed':    mark_failed_once(refund.id, refund.failure_reason)
  case 'canceled':  mark_canceled_once(refund.id)
  case 'pending':   schedule_reconciliation(refund.id)
  case 'requires_action': notify_operator_with_safe_instructions(refund.id)

Функции обновления должны быть идемпотентными. Повторный webhook `succeeded` не создаёт вторую бухгалтерскую проводку и не отправляет клиенту пять писем. Переход из финального состояния назад в pending блокируется и уходит на ручную сверку.

Webhook проверяется от входа до commit

Факт HTTP 200 на endpoint ещё не доказывает обработку. Подтвердите проверку подписи, сохранение event ID, постановку в очередь и commit транзакции. Обработчик отвечает быстро, а тяжёлую бизнес-логику выполняет worker. Повторная доставка одного event ID должна безопасно завершаться без побочных эффектов.

  • Проверьте, подписан ли endpoint на актуальные события refund, включая `refund.updated` и `refund.failed`.
  • Сверьте секрет подписи именно того endpoint и режима test/live.
  • Найдите ответы 4xx/5xx, timeout и события в dead-letter queue.
  • Не сортируйте изменения только по времени получения: события могут прийти повторно или позже соседних.
  • Сохраняйте provider event ID и версию обработчика для повторного проигрывания.

Reconciliation закрывает пропущенные события

Периодическая задача выбирает локальные возвраты, которые находятся в промежуточном состоянии дольше ожидаемого окна, и читает их у провайдера. Она не создаёт новые refunds. Задача обновляет только допустимые переходы, ограничивает частоту запросов и переводит необычный конфликт в очередь ручной проверки.

Порог не должен обещать клиенту точный банковский срок: время зачисления зависит от платёжного метода и банка. В интерфейсе разделите «провайдер принял возврат» и «деньги отображаются у клиента». Поддержке покажите дату создания, текущий подтверждённый статус и следующий срок автоматической сверки.

Контрольный сценарий воспроизводит потерю события

В тестовом режиме создайте возврат, сохраните его ID и временно заставьте worker завершиться ошибкой после приёма webhook. Затем восстановите очередь и запустите reconciliation. Итоговая запись должна стать финальной ровно один раз, сумма — совпасть с объектом провайдера, а повторная доставка события не создавать дополнительных действий.

Если API провайдера по-прежнему возвращает pending, не подменяйте результат вручную. Зафиксируйте возраст операции, payment method, request ID и обратитесь в поддержку провайдера по безопасному идентификатору. Ручной статус без финансового подтверждения маскирует проблему и ломает дальнейшую сверку.

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