Промежуточный статус возврата нельзя исправлять повторным нажатием кнопки. Сначала запросите у платёжного провайдера тот же refund по его идентификатору, сравните ответ с журналом webhook и только затем синхронизируйте локальную запись. Новый refund допустим лишь после подтверждения, что прежняя операция не была создана.
У зависания обычно две разные причины: провайдер действительно ещё ждёт завершения операции либо финальное событие не дошло до приложения. В Stripe объект Refund может иметь состояния `pending`, `requires_action`, `succeeded`, `failed` и `canceled`. Эти значения нужно отобразить на собственную машину состояний, не превращая сетевой timeout в финансовый результат.
Сначала соберите одну временную линию
| Источник | Что выписать | Что доказывает |
|---|---|---|
| Локальная база | refund ID, payment ID, сумма, валюта, created_at, updated_at | Какое состояние видит продукт |
| Ответ create refund | HTTP status, provider refund ID, status, request ID | Принял ли провайдер запрос |
| API провайдера сейчас | Текущий status и failure reason | Фактическое состояние на момент сверки |
| Webhook endpoint | event 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 и обратитесь в поддержку провайдера по безопасному идентификатору. Ручной статус без финансового подтверждения маскирует проблему и ломает дальнейшую сверку.