Лимит в поле админки защищает только от опечатки одного оператора. Два параллельных запроса могут оба увидеть одинаковый остаток и вместе превысить платёж. Сервер должен сравнить сумму с доступным остатком внутри транзакции, создать единственную операцию возврата и передать платёжному провайдеру стабильный idempotency key.
Источником верхней границы служит успешно списанная сумма в той же валюте за вычетом уже успешных и зарезервированных возвратов. Не подставляйте итог заказа: он мог измениться после оплаты, включать бонусы или несколько платежей. Каждый refund связывается с конкретным charge либо PaymentIntent и хранится в минимальных единицах валюты.
Остаток считается по платёжному объекту
available_to_refund = captured_amount
- succeeded_refunds
- pending_refund_reservations
if requested_amount <= 0:
reject('invalid_amount')
if requested_currency != payment_currency:
reject('currency_mismatch')
if requested_amount > available_to_refund:
reject('refund_exceeds_remaining')Формула условная: статусы провайдера нужно отобразить на собственную модель. Не вычитайте failed или canceled refund как завершённый, но не освобождайте pending-сумму до подтверждённого исхода. Иначе второй оператор успеет потратить тот же остаток, пока первый запрос ещё обрабатывается.
Одна транзакция резервирует право на возврат
Заблокируйте строку платежа или отдельного агрегата возвратов, повторно вычислите остаток и создайте запись `refund_requested`. После commit worker обращается к провайдеру. Держать транзакцию открытой во время HTTP-запроса не стоит: внешний сервис может отвечать долго, а блокировка остановит остальные операции.
| Состояние | Входит в занятый остаток | Следующее действие |
|---|---|---|
| requested | Да | Отправить провайдеру с idempotency key |
| provider_pending | Да | Ждать webhook или выполнить безопасную сверку |
| succeeded | Да | Зафиксировать balance transaction и уведомить клиента |
| failed | Нет после подтверждения | Сохранить причину и вернуть остаток |
| unknown | Да | Не повторять с новым ключом; выяснить состояние прежнего запроса |
Статус `unknown` нужен при разрыве соединения: провайдер мог принять запрос, а приложение не получило ответ. Новый refund с новым ключом опасен. Сначала найдите результат по idempotency key, provider refund ID или списку возвратов исходного платежа.
Повторный клик должен вести к той же операции
Сформируйте idempotency key на стороне приложения до сетевого вызова и сохраните его рядом с refund request. Повтор API-запроса пользователя возвращает существующую операцию. Retry worker отправляет тот же ключ и те же параметры; изменение суммы под старым ключом считается ошибкой модели.
- Запретите клиенту передавать произвольный payment ID без проверки заказа и прав оператора.
- Сравнивайте суммы как целые minor units, а не числа с плавающей точкой.
- Логируйте внутренний refund ID и статус, но не данные карты и не секретный ключ провайдера.
- Разделите возврат денег, отмену заказа и возврат бонусов: это разные операции.
Провайдер остаётся внешней стороной сверки
Stripe, например, разрешает несколько частичных refunds только до оставшейся невозвращённой суммы charge и отклоняет превышение. Это дополнительная защита, но локальная админка всё равно должна показывать корректный остаток и обрабатывать отказ без ложного статуса «деньги возвращены».
Webhook обрабатывайте идемпотентно: одно событие может прийти повторно, а события разных операций — в другом порядке. Обновление выбирает refund по provider ID и разрешает только допустимый переход состояния. Не создавайте новый возврат из webhook.
Тест на гонку важнее ручной проверки формы
Возьмите тестовый платёж на 10 000 minor units и одновременно отправьте два возврата по 7 000. Ровно один должен получить резерв, второй — контролируемый отказ или меньший доступный остаток. Затем оборвите соединение после отправки провайдеру и убедитесь, что retry использует прежний ключ, а суммарный succeeded не превышает captured amount.
Для разбора подготовьте временную линию внутренних статусов, суммы в minor units, валюту, idempotency key в маскированном виде и provider refund IDs. Полные платёжные данные клиента для поиска гонки не нужны.